Oxen – AI Agent Module for NexoPOS with Tools, Approvals & MCP

Oxen (NsOxen) brings permission-aware AI assistance into NexoPOS. It helps users understand live store data, perform
supported management tasks through an approval workflow, and connect external AI clients through MCP—all while
preserving NexoPOS permissions, store isolation, validation, and auditability.

What Oxen delivers

• A conversational assistant available from the NexoPOS dashboard.
• Answers grounded in current products, customers, orders, inventory, taxes, payments, and other store data.
• Live activity updates as the assistant starts, completes, or fails tool calls.
• Approval-controlled write operations with permission rechecks and idempotent execution.
• Shared tools for the embedded assistant and authenticated MCP clients.
• Usage controls, operation auditing, and secure credential storage.

Embedded assistant

The dashboard assistant provides a persistent conversation experience without requiring users to leave their current
workflow. It supports:

• Conversation history and contextual follow-up questions.
• Provider-side response chaining and automatic compaction for faster long-running conversations.
• Awareness of the current dashboard route and supported business entities.
• File and image attachments where supported.
• Progressive tool activity while the assistant works.
• Safe Markdown rendering and sanitized output.
• Proposal cards for reviewing, approving, rejecting, or retrying actions.

The assistant only sees tools the current user is allowed to use. Store identity and authorization are resolved by
the application and are never accepted from model-generated arguments.

Store intelligence

Oxen can ground conversations across the main areas of a NexoPOS store:

Safe store management

Supported management actions include creating and updating products, categories, providers, customers, customer
groups, units, unit groups, taxes, tax groups, and coupons. Oxen can also import products, adjust product quantities
and unit settings, upload or replace media, generate product imagery and store logos, update approved store
settings, and generate downloadable reports.

Every mutation is handled as a proposal. The model can prepare an action, but it cannot apply the change directly.
An authorized user must approve the proposal before Oxen executes it.

Destructive or externally billable actions receive an additional confirmation guard. This includes operations such
as deleting media, replacing binary media content, and generating images.

Approval and security model

Oxen follows a controlled execution flow:

1. A user asks the assistant to inspect or change store data.
2. Oxen exposes only tools allowed by the user’s NexoPOS permissions.
3. Read tools execute and return grounded data; write tools create an opaque proposal.
4. The user reviews and approves the proposed action.
5. Oxen rechecks the user, store, permissions, proposal integrity, and expiration before execution.
6. The operation runs idempotently and its outcome is recorded for audit.

Additional safeguards include:

• Encrypted storage for provider credentials.
• Strict schemas and rejection of unexpected tool arguments.
• Validation against authoritative NexoPOS services, models, and relationships.
• Store-scoped access and trusted application context.
• Redaction of sensitive values from logs and model-facing data.
• Rate limits, daily message limits, token limits, and per-turn tool-call limits.
• Replay protection and conflict detection for approved operations.

Media and branding

Oxen can upload new media and replace the contents of existing media without breaking its stored identity or
references. Replacements preserve the media ID, slug, extension, and URL, validate the detected file type,
regenerate image thumbnails, and use a staged filesystem swap so the original remains intact if processing fails.

Store-logo generation creates two transparent PNG assets:

• A square logo for ns_store_square_logo.
• A landscape logo for ns_store_rectangle_logo and ns_invoice_receipt_logo.

The existing logo configuration remains unchanged until both images have been generated, validated, and uploaded
successfully.

Reports and exports

The assistant can prepare supported operational reports and exports in HTML, PDF, or CSV format. Generated files use
temporary signed download links so access remains time-bound and controlled by the application.

MCP integration

Oxen exposes the same permission-aware tool registry through its embedded assistant and the Laravel MCP server
at /mcp/oxen. MCP connections use Sanctum authentication, Oxen token abilities, connection checks, and the
current NexoPOS store context.

This shared registry keeps validation, authorization, proposal handling, idempotency, and auditing consistent
regardless of which supported client invokes a tool.