Final POS – Custom POS Builder

Hand a task in words to Finai, Final's own AI agent, and get its finished answer. It runs as this connection's user on its company, within the allowed packs, and uses Final's tools itself (looking records up, creating products, building or deploying an app). Use it for multi-step merchant jobs you would rather describe than orchestrate; call tools directly when you need the raw data. Pass conversationId to continue an earlier thread.

Run a read-only tool from any allowed pack by its full name (for example hub_find_low_stock) without it being listed. Only tools that read are accepted; tools that change data run through call_write_tool. Arguments follow that tool's own input schema, which find_tools returns.

Run a tool that creates, changes, deletes, sends or deploys from any allowed pack by its full name (for example hub_update_product) without it being listed. Only tools find_tools marks as writes are accepted; read-only tools run through call_tool. Arguments follow that tool's own input schema, which find_tools returns.

Remove packs from tools/list for this connection to keep the list short. Tools stay reachable through call_tool and call_write_tool.

Add packs to tools/list for this connection (remembered). Only allowed packs can be listed; the client refreshes its tool list.

Search every allowed pack for tools by what you want to do ("low stock", "create a product", "deploy the app"). Returns matching tool names with their pack, whether they are listed and whether they change data. Run a read-only match with call_tool and a write with call_write_tool, or enable_packs to list its pack.

COPY vetted blueprint widgets into a flow as real files — byte-exact, no transcription. Pass picks of { blueprintId, widgetId } (from list_blueprints / search_blueprints); the widget files land under src/widgets/<blueprint>/ with their command-frame plumbing intact, persisted as a restorable checkpoint + builder-chat note like write_flow_files. Returns a manifest (paths, export names, props, a ready-to-paste import block) — never the code. Compose your screens by importing the manifest paths; adapt an applied widget with a small write_flow_files edit, never a wholesale rewrite, and never re-type code from get_blueprint. A selfPersisting blueprint's copied code reads/writes its OWN custom tables by exact name: this tool PROVISIONS those tables into your organization automatically, possibly under org-scoped names (see `tables` in the result — the copied code already uses the final names) — never create them yourself and never create a lookalike. Tables owned by a platform extension are reported under `extensionTables` (with extensionIds when pinned): only installing that extension provides them (install_extension, with user consent). Secrets the code reads are reported under `secrets` — each missing key gets a fill-in request in the builder automatically; values never travel over MCP. Re-applying a pick restores the widget's vetted contents.

Apply the update reviewed with get_upstream_update. Pass resolutions: exactly one entry per conflict — { path, contents } with the COMPLETE merged file, or { path, delete: true } when the file should not exist. Missing, unknown or ambiguous entries fail the whole call with nothing written (the plan is recomputed here, so re-review if the flow changed since). What it does, in order: saves the current files as a restorable "Before update" checkpoint, lands the merged tree (an open builder tab picks it up safely), records an "Update from upstream vX" checkpoint narrated in the builder chat, re-stamps the clone's update pointer so the next check compares against this release, provisions custom tables the update introduced (org-scoped names — the merged code already uses them), and raises a fill-in request for each missing secret (values never travel over MCP). If the review said adoptMode: true, call with adopt: true and NO resolutions to replace the files with the original's latest release wholesale — undoable via the safety checkpoint; confirm with your user first.

Attach this agent session to an EXISTING flow as a chat in the builder's rail (so the flow's owner sees your work alongside their own chats). Also use log_message to narrate what you're doing.

Create a new custom data table (schema: name + typed columns) in your Final organization. USE THIS for any data the app must keep — loyalty stamps, waitlists, bookings, inventory logs, settings: the platform syncs the table to every station running the flow and keeps it working offline at the POS, so it replaces ANY browser-storage or hand-rolled persistence (localStorage/IndexedDB are forbidden and fail validate_flow). NEVER store credentials in a table — that's what the secrets vault (request_secret) is for. This creates the table IMMEDIATELY and ORG-WIDE (visible to every station and every flow, not just this one), so unless the user actually asked for stored data, confirm before creating; creation can also be plan-gated — surface a plan/permission error to the user rather than retrying. Check list_custom_tables first to reuse an existing table, and search_blueprints before building functionality around a new one: a selfPersisting blueprint brings its OWN tables by exact name and apply_blueprint_widgets provisions them for you, so a lookalike would sit dead while the feature keeps reading the real one. Create tables only for net-new data no applied blueprint persists. The name is normalized to kebab-case; generated code reads/writes rows via renderClient.getCustomTableData / upsertCustomTableData.

Create a new, empty flow (app build) in your Final organization for YOU to write the app into. It appears in the Miami builder immediately, with this agent session attached as a chat. Optional theme knobs seed the live palette. Optional `device` ("mobile", "kiosk", "iphone", …) sets the preview frame it opens in; see set_flow_device. Returns the flow id and a builder deep link. Call get_scaffold before writing files. For an app the user merely DESCRIBED, use start_build.

Create a NEW flow that starts as a complete, vetted application rather than an empty file tree — the fastest path to a working build when an FBB (a Final Business Blueprint: a whole app) matches what the user wants. For an app the user merely DESCRIBED, use start_build (the website's own start picks the FBB); this verb is for when the user asked YOU to copy one. Find one with search_blueprints({ kind: "fbb" }). The app's screens, navigation and command-frame wiring are copied byte-exact from the build the FBB points at, its custom tables are re-created under THIS organization's names (the copied code already uses those names — keep them), and a fill-in request is raised for each secret it reads. This ALWAYS creates a new flow: an FBB cannot be merged into an existing build (there are no screen-graph merge semantics). To add parts to a build you already have, use apply_blueprint_widgets instead. THE COPY ENDS YOUR TURN. It is the finished deliverable, not step one — the app is vetted and already runs. When it returns, say its `report` line and stop: do NOT preview, validate, edit or extend it, and do not start on anything else the user described. The result names the tools not to call.

Remove files from a flow's tree by path. Engine-owned paths are rejected. Recorded as a checkpoint + chat note like writes.

Direct deploy for CI/agent workflows: builds the app in a server sandbox (npm install + vite build) and publishes the dist to Final web-hosting as a new live version. Two things stop a deploy: a failing build, and a hardcoded credential (a build is distributable to other companies, so a baked-in secret would ship to all of them — use request_secret). Guardrail and type findings do NOT block; run validate_flow first if you want them. Omit `changelog` and the release notes are drafted for you from what changed since your last deploy — call log_message (or pass `note` on write_flow_files) as you work so those notes describe intent rather than just file names. Uses your organization's provisioned hub credential automatically (the same long-term org JWT the extension tools use) — no token argument needed once you've connected. Pass `hostingToken` only as an escape hatch to override it; if no credential is available, reconnect via the Connect dialog or use open_in_builder and deploy from the Launch tool instead.

INSPECTION ONLY — read a blueprint's overlay code by id (from list_blueprints) to understand how it works. To USE a blueprint, apply it: apply_blueprint_widgets for a widget-set (materializes its widgets byte-exact with the command-frame plumbing intact AND provisions the custom tables its code depends on), create_flow_from_blueprint for an FBB. Do NOT re-type code from this tool into write_flow_files — that silently drops the vetted plumbing and leaves its tables unprovisioned. `tables` (when present) lists the custom tables the code binds to by exact name. For a WHOLE-FLOW blueprint this returns the screen manifest WITHOUT file bytes by default — an entire app is far too large to read this way, and you never need to: instantiation copies it server-side. Pass includeFiles: true only to audit the source.

Authoritative server-side health probe of the flow's preview sandbox, plus a short snapshot of recent dev-server logs (useful to diagnose a red screen or crash).

The contract every Final flow app is built against: which files the ENGINE owns (never write them — they are re-asserted verbatim), the baseline package.json (Vite + React 19 + TS + Tailwind + command-frame), the rules your files must follow, and the runtime contracts that compile and preview fine but fail on a real device (money in minor units, the first-load handshake, getX response unwrapping, tender success semantics). Call this once before writing any files; pass `device` for layout guidance.

Has the build this flow was copied from released a newer version? Covers both a "Make it yours" clone of a listing and a build started from an FBB. Returns update.status: "available" (a newer deployed release exists — review it with get_upstream_update), "current" (up to date), "unknown" (the original has no comparable release), or "gone" (the original was DELETED — for a share clone, also if it was un-shared; an FBB's parent stays reachable while it exists, because the catalog vouches for it rather than the owner's share toggle), with the release notes published since the copy. Flows that are not snapshot-sourced copies return update: null. Cheap — safe to call whenever the user asks about updates.

Review what an update from the original build would change — the same review the builder shows its maker, shaped for an agent. Returns the releases since the clone, the clean changes (added/changed/removed paths, with full incoming contents for added+changed), and CONFLICTS: files where this flow's own edits and the update collide, each with complete base/ours/theirs contents. RESOLUTION CONTRACT (match the builder's behavior): when both sides' changes serve different purposes, merge them yourself — one file keeping BOTH sides' improvements; never wholesale-pick a side out of convenience. ONLY when the two sides genuinely contradict on the same visible thing (a color, a layout, a label, a behavior) ask YOUR user which they want, in plain product language — describe the visible difference, never file names or code. Then call apply_upstream_update with exactly one resolution per conflict. The trees you see are already in THIS organization's table namespace — never rename tableName literals yourself. adoptMode: true means the merge base is unrecoverable, so no merge is possible: offer the user adopting the latest release wholesale (apply_upstream_update with adopt: true) or staying put. upToDate: true means there is nothing to do.

Install an extension ORG-WIDE: creates the install link on EVERY company in your Final organization (demo companies included), skipping companies that already have it, so it is safe to retry. Installing is deliberate and org-visible — confirm with your user and call this ONLY when they explicitly asked for the extension. Find the id with list_extensions (organization and public extensions both install); after a successful install the extension's surfaces become embeddable — inspect them with list_extension_surfaces and build the ones carrying requirementsMd natively instead of embedding. Per-company failures are collected in the result rather than thrown, and `installState` reports the org-wide outcome (installed / partial / none).

List EVERY vetted, type-checked blueprint available to reuse — working functionality (gift cards, loyalty, payment surfaces, product grids, carts, customer views, order tickets, receipts), not just screen layouts. Check the catalog BEFORE creating custom tables or hand-rolling a capability. Returns id, kind, slot, title, summary, surfaces, tags, and selfPersisting per blueprint — selfPersisting: true means it reads/writes its OWN custom tables by exact name inside its code, which applying then provisions in your organization automatically (some are extension-owned and come from installing that extension); never create a table for a feature it covers. TWO KINDS, used differently: kind "widget-set" (the default this returns) is a set of parts you copy into an existing build with apply_blueprint_widgets; kind "fbb" is a Final Business Blueprint — a COMPLETE APP. It has no widgets to copy and is used with create_flow_from_blueprint to start a NEW flow. Pass kind: "fbb" to browse complete apps, or kind: "any" for both. To find the best match for a specific capability instead of scanning the whole catalog, use search_blueprints. get_blueprint is read-only inspection.

List your organization's custom data tables with their column schemas. Custom tables are Final's built-in, station-syncing database — data written on one station is automatically synced to every other station running the flow, and keeps working OFFLINE at the point of sale. They are the ONLY sanctioned persistence for generated apps (browser storage is per-device, never syncs, and is wiped on real Render terminals — validate_flow rejects it). Call this before create_custom_table to reuse an existing table instead of duplicating one. For NEW functionality, check search_blueprints before designing tables — a vetted blueprint may already provide the feature, and a selfPersisting blueprint's tables may NOT appear in this list (often extension-owned, resolved by name at runtime): their absence is never a reason to create lookalikes. Generated code reads/writes rows at runtime via renderClient.getCustomTableData / upsertCustomTableData (ground with lookup_command_frame).

List the CUSTOM TABLES an extension registers (table name + typed columns), so generated code can read/write its data at runtime via renderClient.getCustomTableData / upsertCustomTableData by table name (ground the calls with lookup_command_frame). Only the org's OWN extensions expose their tables — a public / other-org extension returns an empty list with a note. Pass the extension's id from list_extensions; the org's non-extension tables come from list_custom_tables. Read-only. Does not write files.

List the SURFACES an extension exposes — embeddable iframe injection points, each with a surfaceId, a platform (builder/hub/render), a type, and a url. Render an installed surface inside a generated screen with the engine component `<ExtensionSurface surfaceId="<surfaceId>" />` (ground it with lookup_engine_component). A surface may carry `requirementsMd` — full markdown build instructions for re-implementing it NATIVELY in the app: when present, prefer building that surface as first-class native screens in the app's own styling with real command-frame wiring, and embed `<ExtensionSurface>` only for surfaces without it. Works for the org's own extensions (hub credential) and public ones (resolved via the public marketplace, no credential needed). Pass the extension's id from list_extensions. Read-only. Does not write files.

List the platform EXTENSIONS available to your organization — the org's own plus the public marketplace — so you can suggest, inspect, or install one. Each entry carries an id, label, category, short description, and its source (organization or public); public results need no hub credential, and a note tells you when the org-owned side was unavailable. Pass query with the capability the user asked for — results are relevance-ranked against it (label, category, and the vocabulary of the blueprints each extension enables) and capped to the genuine matches, so an empty list means NO extension provides that capability. Omit query to browse the whole catalog with skip/limit paging — publicTotal reports how many marketplace rows exist. Inspect a result with list_extension_surfaces / list_extension_custom_tables; install it org-wide with install_extension ONLY when your user explicitly asked for it. Read-only. Does not write files.

List the flows (app builds) in your organization, newest first: id, title, timestamps, and live theme knobs. Final staff sessions also see Final's own flows, marked owner: "Final". Use a flow id with the other tools, or create_flow to start fresh. Clones of listed builds carry an upstreamUpdate field when the build they were copied from has released a newer version — review and apply it with get_upstream_update / apply_upstream_update.

List the key NAMES already stored in your organization's encrypted secrets vault — never the values (no tool returns a secret value). Use this to (a) reuse an existing key instead of requesting a new one, and (b) poll whether a request_secret ask has been fulfilled by the human. Generated code reads a secret at RUNTIME with renderClient.getSecretVal({ key }) — the build ships key names only.

Record a message in this agent's chat inside the builder — the user's request (role 'user') or your own progress/summary (role 'assistant'). Keeps the builder timeline faithful to what happened in this session.

Look up the EXACT, version-locked command-frame API a generated Final POS app runs on: renderClient method signatures + params, CF* entity field lists, pub/sub topic event vocabularies, and worked examples. Pass one of method/entity/topic for a precise lookup, entity+field to confirm a field exists, query for fuzzy search, or the plural batch forms. Ground every renderClient call in this before writing it — fabricated fields/methods fail on real Render devices. Typed signatures and entity fields are authoritative; the worked examples come from upstream docs and are NOT typechecked, so where they disagree, trust the types. Results carry `traps` for known field-level gotchas.

Look up the exact props/signature of an engine-owned `./final/*` helper: the `@/final/ui` primitives (Button, IconButton, Card, Tile, Input, Field, Chip, ListRow, Dialog, Sheet, Toolbar, Heading, EmptyState, cn) plus usePrint, StationHomeButton, SwitchUserButton, useStationHome, Barcode, BootSplash. These are re-asserted into every generated app — compose screens from the primitives (see get_scaffold contracts.designLadder) and import the rest instead of hand-rolling buttons/cards/dialogs, printing, station-home/switch-user, barcodes, or the loading splash. Pass name for a precise lookup, query for fuzzy search, or neither to list all.

Look up the Final POS REST API (https://api.finalpos.com) — endpoint method/path, request fields, response shape, and a worked fetch example. This is the ONLINE-ONLY fallback for admin/management operations command-frame cannot express (creating products/variants/categories, customer management, outlets/stations/tax tables, webhooks). Command-frame is ALWAYS first choice for live POS data — it works offline and the host owns money/totals. A call to this API is network egress from the station: it fails whenever connectivity does, so never put one in the sale path — use it for setup/admin work and degrade gracefully. Pass resource to list a domain, operation for one endpoint, or query for fuzzy search.

The recommended way to finish: a deep link that opens this flow in the Miami builder, where the owner can review the work, restore checkpoints, and deploy through the Launch tool (validation gates, listing media, changelog, version history).

Read a flow's generated source tree. Omit `paths` to list all file paths (cheap); pass `paths` to fetch specific files' contents.

Rename a build (flow) authoritatively across the platform in one call: the builder header, list_flows / open_in_builder, and the Deerlake catalog all reflect the new title, and updatedAt is bumped. A deployed build keeps its hosted web app: the hostname and version history are unchanged, and the next deploy_flow publishes the next version. Does NOT edit the app source: rename a hardcoded old name yourself with write_flow_files.

Ask the flow's owner to enter a third-party credential (API key, auth token, webhook secret) into Final's encrypted vault. THIS TOOL TAKES NO VALUE and no tool ever returns one — the human types it into a masked input in the Miami builder, and it goes straight into the vault. Why: flow builds are DISTRIBUTABLE to other companies, so a credential must never be baked into the code (validate_flow and deploy_flow scan for and block hardcoded secrets). Your generated code reads it at RUNTIME with renderClient.getSecretVal({ key }) and must degrade gracefully while the key isn't stored yet (disable the integration + tell the user to configure it — never crash). After calling this: tell YOUR user to open the builder link and enter the value, and poll list_secret_keys to detect when it lands.

SEMANTIC search over the vetted blueprint catalog — matches are ranked by what you MEAN, not by shared words, so describe the capability in plain language ('rewards for repeat customers' finds the loyalty blueprint). RUN THIS FIRST — before creating custom tables or hand-rolling a capability: blueprints ship working FUNCTIONALITY (gift cards, loyalty, payment surfaces, carts), not just screen layouts. Search once per FEATURE you're adding (smart grid, gift cards, loyalty points, receipts) and REPEAT it for each distinct capability rather than issuing one broad query — a build usually combines several. Returns { results, note? }: blueprint summaries (id, slot, title, summary, surfaces, tags, selfPersisting, match score in [0,1]) best match first. selfPersisting: true means the blueprint reads/writes its OWN custom tables by exact name inside its code, and apply_blueprint_widgets provisions them in your organization automatically (extension-owned ones come from installing that extension) — NEVER create a table for a feature it covers. Prefer this over list_blueprints when you know what you need. Pick the widgets you need and copy them with apply_blueprint_widgets({ flowId, picks }) — applied ON TOP of the current build, never replacing it. Low match scores across the board mean no vetted blueprint fits — only then build that piece from scratch grounded in the command-frame docs. Optional `slot`/`surface` narrow the results; `limit` caps how many are returned (default 10).

Boot the flow's server-side preview sandbox (Vite dev server) — or reconcile a running one to the flow's current files — and return its public HTTPS URL already pinned to this flow's mock dataset: the maker's pick, else its vertical's (sushi, not restaurant). Open the URL in a browser to see the app; call again after write_flow_files to sync. Previews idle-stop on their own; call stop_preview when done to free resources sooner.

Stop the flow's preview sandbox and free its resources. The next start_preview cold-boots in a couple of seconds.

Reconcile a (running or cold) preview sandbox to the flow's current files and run the green-build gate (tsc + vite build). Returns the gate result — the fastest way to know your code actually compiles. The engine forces parts of package.json on every sync: the dev/build/typecheck scripts, and the vendored command-frame + mock packages to their bundled tarballs. Baseline and build dependencies are re-added only when you declared them nowhere, so your own additions and pins survive. Shares one rate bucket with start_preview — sync once per change-set, not per file.

Evolve an EXISTING custom data table's schema: add columns, change existing ones (rename/retype — destructive for stored rows, use sparingly), or drop columns. The table is identified by its kebab-case name from list_custom_tables. Tables are ORG-WIDE, so a schema change lands for every flow and station already using this one — check who reads it before reshaping. NEVER rename or reshape a table a selfPersisting blueprint reads/writes — its copied code references the exact current names. Per-operation failures are collected rather than aborting the whole change. Row data itself stays a runtime concern of the generated app (renderClient).

Deterministic STATIC checks against the platform contract: (1) guardrails — fabricated renderClient methods, forbidden browser APIs/imports, engine-file writes; (2) a REAL TypeScript check of command-frame usage against the PINNED .d.ts the app installs (the version is stamped in the result) — this proves TYPES, never runtime behaviour and never device parity; (3) a hardcoded-credentials scan; (4) `flowTypeErrors` — a whole-tree `tsc` against REAL react types, which catches what (2) cannot see (e.g. a `useEffect` cleanup that returns a value, a hard TS2345 the builder's in-chat gate will report to whoever opens this flow); plus advisory `warnings` (client money math, hardcoded catalog data, missing station-home/data-test, tip-as-cart-fee) that don't affect `clean` but each predict a real on-device failure. secretFindings BLOCK deploy_flow; everything else is advisory. Run it after each write batch, before start_preview.

Create or overwrite files in a flow's tree (full contents, not diffs). Engine-owned paths are rejected — see get_scaffold. Every write lands as a restorable checkpoint and is narrated in the builder chat. If a live preview is running, follow up with start_preview to sync it. Validate with validate_flow before deploying. If a call returns an error the files may STILL have landed (and a very large payload can truncate mid-file) — re-read with read_flow_files before retrying, never blind-retry. Because writes replace whole files, keep files small and single-purpose so an edit can't clobber unrelated working code.

Who this connection acts as: organisation, user, the company Hub tools act on and the companies you may switch to, the allowed and listed packs, and how to reach tools that are not listed.

Add a note to a customer — an allergy, a preference, what happened with an order. Existing notes are KEPT; this appends. Takes the customer ID from get_customers. Staff read these in the cabinet, so write what the merchant said, not your own summary.

Add one choice to an existing modifier, leaving the rest alone. This is the safe way to extend a modifier — unlike update_modifier, it cannot drop anything. Appends to the end unless sortOrder says otherwise. price is the extra charge per unit as a human amount ("0.70"); omit it for a choice that costs nothing, which still prints on the receipt.

Add photos to an existing product — from public URLs, or as base64 bytes when the merchant attached the file itself and there is no URL. URL images are downloaded and stored on the platform, so the product never depends on someone else's site staying up. Existing photos are KEPT — this adds to them. JPEG/PNG/WebP/GIF/HEIC, up to 20MB each. Takes the product ID from get_products, never a name.

Add an EXISTING rate to a tax group, or change that rate’s compounding flag within the group. Both ids come from get_taxes. This shares the rate — it does not copy it. The group starts charging the rate’s existing per-outlet percentages, and a later edit to that rate changes this group too. Use create_tax_rate instead when the rate does not exist yet. The rate is appended last in the charging order; use update_tax_group with rateIdsInOrder to move it. CONFIRM WITH THE MERCHANT — this immediately adds tax to every product in the group. Sales already rung up are NOT recalculated — this only affects sales from now on.

Change the count of ONE variant at ONE outlet — the cabinet's "Adjust Inventory" action. CONFIRM WITH THE MERCHANT FIRST, repeating the product, the outlet, the reason and the number: this writes immediately, is permanently recorded against the employee in the stock history, and there is no undo from here. Reasons: STOCK_RECEIVED (a delivery arrived) and RESTOCK_RETURN (a return put back on the shelf) ADD the quantity; DAMAGE, THEFT and LOSS SUBTRACT it; INVENTORY_RECOUNT SETS the count to exactly the quantity you pass (a physical stocktake). Always pass quantity as a positive number — the reason decides the direction. Pick the reason the merchant actually gave; these end up in reports, so recording theft as damage misstates their loss. If stock is not tracked for that variant at that outlet, NOTHING is written and the result says applied: false — do not report success, and do not read it as "the stock is 0". Tracking has to be turned on for the product first. To move units between outlets use create_stock_transfer instead.

Move a team member onto a different role — this is how someone gains or loses access. Answers 'give Maria access to the reports', 'make him a cashier again', 'take away her permissions'. PERMISSIONS ARE POWER. Confirm with the merchant first, naming the person and the role out loud ("give Maria the Manager role — yes?"), and never act on a role change you inferred rather than were asked for. The change is live on the next request: rights are re-read from the role every time, so no one logs out and no agent key stops working — including yours, if the change reaches your own account. It swaps their WHOLE permission set for that role’s, so read get_roles first and check the new role really carries what the merchant asked for and nothing dangerous besides — if no existing role fits, say so rather than picking the closest one. You may also point the merchant’s own account at another role, including the account this agent key belongs to, which would change your own permissions from the next call onward: never do that unless the merchant asked for it in those words. To change what a role itself allows, without moving anyone, use update_role.

Release a booked window. The order stays as it is — cancelling a booking is not a refund, and money is never moved here; if the customer is owed money, do that on the order. Confirm with the merchant before cancelling a booking somebody already paid for.