@fleetless/contracts 1.0.0

package/dist/jobs.js

@@ -0,0 +1,345 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { slug, wireSeqCursor, wireTimestampMs } from './common.js';
+/**
+ * Jobs (spec §6.1, §11.3): one running unit of work on a robot — an action
+ * goal or a service call — with an id both sides know, so bridge and cloud
+ * stay in sync across a disconnect.
+ *
+ * Two rules shape everything here:
+ *
+ * 1. **State is observed by slug, not by id.** The id is informative (§11.3);
+ *    a client watches `robot × slug` and sees whatever job is running there,
+ *    which is also why every observer of a slug sees the same job.
+ * 2. **`lost` is a real outcome and must be said out loud** (§6.1). Job state
+ *    lives only in the bridge's memory; if it restarts mid-job, the results
+ *    are gone. The cloud then marks the job `lost` — never leaves it reading
+ *    "running" because nobody contradicted it. A system that reports a
+ *    machine is still working when it does not know is worse than one that
+ *    admits it lost track.
+ */
+export const jobState = z.enum(['running', 'succeeded', 'failed', 'cancelled', 'lost']);
+export const job = z.object({
+    id: z.uuid().meta({
+        description: 'The job\'s id, minted by the cloud when the invocation is accepted. Informative: state is observed by slug, and this id is what a cancel names when a caller wants to stop one specific job rather than whatever is running.',
+    }),
+    robot_id: z.uuid().meta({ description: 'The robot this job is running on.' }),
+    slug: slug.meta({
+        description: 'The action or service this job is running, as the published configuration exposes it. One slug carries one job at a time, so every observer of that slug sees the same one.',
+    }),
+    state: jobState.meta({
+        description: 'Where the job stands: `running`, `succeeded`, `failed`, `cancelled` or `lost`. `lost` is a real outcome — the bridge restarted mid-job and the result is gone — and is said out loud rather than left reading `running` because nobody contradicted it.',
+    }),
+    started_at: z.iso.datetime().meta({
+        description: 'When the cloud minted this job, as an ISO 8601 timestamp. For a job adopted from a reconnecting bridge it is **adoption time**, not the real start, because the cloud never minted it and has no honest alternative.',
+    }),
+    updated_at: z.iso.datetime().meta({
+        description: 'When this job last changed, as an ISO 8601 timestamp.',
+    }),
+    /**
+     * A monotonic counter, ascending in mint order (W7), and the **named**
+     * tiebreaker for any listing that claims an order.
+     *
+     * `started_at` is not a total order: two jobs minted in the same millisecond
+     * sort against each other arbitrarily, and arbitrarily means *differently on
+     * each query* — so `GET /api/robots/:id/jobs`, which documents "newest
+     * first", can show one twice and the other not at all. Exactly the defect
+     * `auditEvent.seq` was added for in W6b, in a route the same wave shipped.
+     *
+     * **Scoped honestly: per cloud process, per run.** Job state lives in memory
+     * (§6.1 — that is why `lost` exists at all), so this counter restarts when
+     * the cloud does, alongside the jobs it orders. Sound, because it only ever
+     * orders jobs that coexist in one registry — and stated, because a reader
+     * who assumed `auditEvent.seq`'s durable semantics would be wrong.
+     */
+    seq: z.number().int().positive().meta({
+        description: 'A monotonic counter ascending in mint order, and the named tiebreaker for any listing that claims one — `started_at` alone is not a total order. Scoped per cloud process and per run: job state lives in memory, so this restarts with the registry it orders.',
+    }),
+    result: z.unknown().nullable().meta({
+        description: 'What the call returned once it succeeded, shaped by the ROS action or service itself. `null` until then, and for a job that did not succeed.',
+    }),
+    /**
+     * Present on `failed`; a human message, plus a code where one exists.
+     *
+     * `details` exists because a refusal that carries only prose forces every
+     * consumer to parse it. W6b shipped `job_queue_full` with a documented
+     * `{limit, queued}` payload and **nowhere to put it**: the bridge reports a
+     * full queue as a job error, this shape had no `details`, and so the numbers
+     * were formatted into the message and lost. The console then rendered a
+     * "wait for one of N to finish" alert from a shape nothing in the system
+     * produced, and its test built that shape by hand — three repos agreeing
+     * with each other about a payload none of them exchanged (Momus, W6b
+     * review).
+     *
+     * Optional, because most job errors have nothing structured to add. Where a
+     * code has a documented payload — `job_queue_full` has
+     * `jobQueueFullDetails` — it belongs here, not in the sentence.
+     */
+    error: z
+        .object({
+        code: z.string().min(1).meta({
+            description: 'A machine-readable code for the failure, such as `job_queue_full`, where one exists for it.',
+        }),
+        message: z.string().min(1).meta({
+            description: 'A human-readable sentence saying what went wrong.',
+        }),
+        details: z.unknown().optional().meta({
+            description: 'The structured payload belonging to `code`, for the codes that document one — `job_queue_full` carries its `limit` and its `queued` count here. Absent for a failure with nothing structured to add, which is most of them.',
+        }),
+    })
+        .nullable()
+        .meta({
+        description: 'Why the job failed: a human `message`, a `code` where one exists, and `details` for the codes that carry a documented payload. `null` unless `state` is `failed`.',
+    }),
+});
+/**
+ * One update about a job, pushed to subscribers of its slug.
+ *
+ * `timestamp_ms` is the bridge's capture time, exactly as for a datapoint
+ * (§6.3 says action feedback carries it too) — so a client computes the age
+ * of a progress report the same way it computes the age of a sensor value,
+ * and a burst of late-delivered feedback after a reconnect is visibly late
+ * rather than looking current.
+ */
+export const jobEvent = z.object({
+    type: z.literal('job'),
+    robot_id: z.uuid(),
+    slug,
+    job,
+    /** Action feedback, if this update carries any. */
+    feedback: z.unknown().nullable(),
+    /** 0..1 when the action reports progress; null when it does not. */
+    progress: z.number().min(0).max(1).nullable(),
+    timestamp_ms: z.number().int().nonnegative(),
+});
+/**
+ * What a busy refusal tells the caller (spec §11.3: "inkl. Information, was
+ * läuft"). A refusal that only says "busy" forces the caller to guess whether
+ * to wait or to give up.
+ */
+export const busyDetails = z.object({
+    running: job,
+});
+/**
+ * What a `publisher_busy` refusal tells the caller (spec §6.4).
+ *
+ * "Another caller is publishing and has not been quiet long enough" names a
+ * state and no action: the caller does not know how much longer, because
+ * `quiet_timeout_ms` lives in the configuration document, which a client app
+ * never reads. Without a number they busy-loop — on the one verb that moves
+ * a machine, on a platform with no rate limiting. So the refusal carries the
+ * wait itself.
+ *
+ * `holder` is deliberately absent: it would name another end user to a
+ * caller who may have no right to know they exist.
+ */
+export const publisherBusyDetails = z.object({
+    /** The configured silence a holder must leave before anyone else may publish. */
+    quiet_timeout_ms: z.number().int().nonnegative(),
+    /** How much of that silence is still outstanding, now. */
+    retry_after_ms: z.number().int().nonnegative(),
+});
+/**
+ * What a `job_queue_full` refusal tells the caller (W6b).
+ *
+ * Both numbers, not just the limit: `limit` alone says how big the queue is
+ * and nothing about whether waiting will help, and `queued` alone cannot be
+ * read without knowing the bound. Together they are the only two facts a
+ * caller needs to decide between retrying and giving up.
+ */
+export const jobQueueFullDetails = z.object({
+    /** The bridge's bound on queued jobs. */
+    limit: z.number().int().positive(),
+    /** How many are queued right now — `>= limit` when this refusal is sent. */
+    queued: z.number().int().nonnegative(),
+});
+/** A page of run history is bounded; 200 is what one console screen can ever want. */
+export const JOB_RUN_PAGE_MAX = 200;
+/**
+ * Job runs keep the audit log's retention, and that is not a coincidence:
+ * every invoke already writes an `action.invoked` audit event. A different
+ * figure here creates a window in which the audit log shows a call whose
+ * outcome has already been deleted — a state no developer can be expected to
+ * read as anything but a bug.
+ */
+export const JOB_RUN_RETENTION_DAYS = 90;
+/**
+ * Who invoked a run.
+ *
+ * Deliberately **not** `auditActor`: that enum carries `bridge` as a fourth
+ * case, and a bridge invokes nothing. An enum that names an impossible case
+ * invites every reader to handle it.
+ *
+ * **`app_user` is what a client-app caller writes now, and `end_user` stays**
+ * (app-user auth, D1). The seam this comment used to describe — two names for
+ * two ways into one merged pool — is settled: the two identity spaces are
+ * separate tables again, and `app_user` is a row in `app_users`, belonging to
+ * exactly one app. `end_user` is kept for the same reason `auditActor.kind`
+ * keeps it: a job run is history, and every row written before the cut carries
+ * it. Removing the member would make the whole trail unparseable to a client
+ * that validates, which is the one thing a history shape must never do.
+ */
+export const jobActor = z.object({
+    kind: z.enum(['developer', 'end_user', 'app_user', 'server_key']).meta({
+        description: 'What the caller was acting as: a `developer` in the console, an `app_user` of one app, or a `server_key` used by server-side code. A bridge invokes nothing, so it is deliberately not a case here. `end_user` appears only on runs recorded before app users replaced the organisation-wide user pool — it is kept so a history page can still render them, and nothing writes it any more.',
+    }),
+    id: z.uuid().meta({
+        description: 'The id of the Fleetless user, app user or server key that invoked the run.',
+    }),
+    /**
+     * The email for a person, the key's `name` for a server key. A display
+     * snapshot taken at invoke time: renaming a key afterwards does not rewrite
+     * history, which is the point of storing it rather than joining.
+     */
+    label: z.string().min(1).max(200).meta({
+        description: 'A display name taken at invoke time — the email for a Fleetless user or an app user, the key\'s own name for a server key. Storing it rather than joining is the point: renaming a key afterwards does not rewrite history.',
+    }),
+});
+export const jobRunKind = z.enum(['action', 'service']);
+/**
+ * One durable record of one invocation (spec `2026-08-20-timeseries-and-run-history`,
+ * D2). One row per run, never one per event: the per-event timeline's write rate
+ * is set by the bridge, and a throttled log that cannot say it was throttled is
+ * the instrument this codebase refuses everywhere else. The live timeline is
+ * delivered in full by realtime, for as long as somebody is watching.
+ */
+export const jobRun = z.object({
+    id: z.uuid().meta({
+        description: 'The run\'s id, which is the same id the invocation was answered with — so a caller that kept a job id can find its durable record here later.',
+    }),
+    robot_id: z.uuid().meta({ description: 'The robot the run happened on.' }),
+    slug: slug.meta({
+        description: 'The action or service that was invoked, as the published configuration exposed it at the time.',
+    }),
+    kind: jobRunKind.meta({
+        description: 'Whether the slug was an `action` or a `service`.',
+    }),
+    state: jobState.meta({
+        description: 'How the run ended, or `running` while it is still going. `lost` means the bridge restarted mid-run and the outcome is unknowable rather than unknown.',
+    }),
+    started_at: z.iso.datetime().meta({
+        description: 'When the run started, as an ISO 8601 timestamp. Runs are listed and filtered by this instant.',
+    }),
+    ended_at: z.iso.datetime().nullable().meta({
+        description: 'When the run finished, as an ISO 8601 timestamp. `null` while it is still `running` — a run has an end only once it has one.',
+    }),
+    duration_ms: z.number().int().nonnegative().nullable().meta({
+        description: 'How long the run took, in milliseconds. `null` while it is still `running`, never `0` standing in for "nothing so far".',
+    }),
+    result: z.unknown().nullable().meta({
+        description: 'What the action or service returned once it succeeded, shaped by ROS itself. `null` otherwise.',
+    }),
+    error: z
+        .object({
+        code: z.string().min(1).meta({
+            description: 'A machine-readable code for the failure, such as `job_queue_full`, where one exists for it.',
+        }),
+        message: z.string().min(1).meta({
+            description: 'A human-readable sentence saying what went wrong.',
+        }),
+        details: z.unknown().optional().meta({
+            description: 'The structured payload belonging to `code`, for the codes that document one. Absent for a failure with nothing structured to add.',
+        }),
+    })
+        .nullable()
+        .meta({
+        description: 'Why the run failed — a `message`, a `code` where one exists, and the structured `details` some codes carry. `null` unless it failed.',
+    }),
+    actor: jobActor.meta({
+        description: 'Who invoked the run, and what they were acting as at the time.',
+    }),
+    /**
+     * **Durable, unlike `job.seq`.** That one is a per-process counter that
+     * restarts with the cloud; this is a postgres `bigserial` and is the cursor
+     * `before_seq` walks.
+     */
+    seq: z.number().int().positive().meta({
+        description: 'The durable cursor this history is ordered and paged by. Unlike `job.seq` it does not restart when the cloud does; it is the value a caller sends back as `before_seq`.',
+    }),
+    progress: z.number().min(0).max(1).nullable().meta({
+        description: 'How far a still-running run has got, as a fraction from `0` to `1`, read live from the in-memory registry. `null` means **not known right now** — after a cloud restart, before the bridge reconnects — and never a `0` standing in for \"no progress yet\".',
+    }),
+    feedback: z.unknown().nullable().meta({
+        description: 'The most recent action feedback for a run that is still running, shaped by the ROS action. Live-only, so it is `null` for every settled run and whenever the registry has nothing.',
+    }),
+});
+export const jobRunQuery = z
+    .object({
+    before_seq: wireSeqCursor.optional().meta({
+        description: 'Return only runs with a `seq` below this value — the next, older page. Send back the `next_cursor` of the previous response rather than computing one.',
+    }),
+    limit: z
+        .union([z.string().regex(/^\d{1,4}$/), z.number().int()])
+        .transform((v) => Number(v))
+        .pipe(z.number().int().positive().max(JOB_RUN_PAGE_MAX))
+        .optional()
+        .meta({
+        description: 'How many runs to return, from `1` to `200`. Absent means `100`. It arrives on the query string, so a numeric string and a number are both accepted.',
+    }),
+    robot_id: z.uuid().optional().meta({
+        description: 'Only runs on this robot. Absent means every robot in the organisation.',
+    }),
+    slug: slug.optional().meta({
+        description: 'Only runs of this action or service.',
+    }),
+    state: jobState.optional().meta({
+        description: 'Only runs in this state — `running`, `succeeded`, `failed`, `cancelled` or `lost`.',
+    }),
+    kind: jobRunKind.optional().meta({
+        description: 'Only `action` runs, or only `service` runs.',
+    }),
+    from_ms: wireTimestampMs.optional().meta({
+        description: 'Only runs that started at or after this unix timestamp in milliseconds. Together with `to_ms` the window is half-open, `[from, to)`, so adjacent windows tile without counting a run twice.',
+    }),
+    to_ms: wireTimestampMs.optional().meta({
+        description: 'Only runs that started **before** this unix timestamp in milliseconds. The window is half-open, so a run starting exactly on `to_ms` belongs to the next one.',
+    }),
+})
+    .strict();
+export const jobRunListResponse = z.object({
+    runs: z.array(jobRun).meta({
+        description: 'This page of runs, newest first by `seq`. Empty means the filter matched nothing, not that the history is gone.',
+    }),
+    /**
+     * The `seq` a caller sends as `before_seq` to keep reading — or `null` when
+     * there is nothing further. **`null` means the end, and that is a promise
+     * rather than an observation.** A caller who instead compares `runs.length`
+     * against `limit` is wrong the moment a filter makes a page thin.
+     */
+    next_cursor: z.number().int().positive().nullable().meta({
+        description: 'The `seq` to send as `before_seq` to keep reading, or `null` when there is nothing further. **`null` is a promise, not an observation** — a caller who instead compares the page length against `limit` is wrong the moment a filter makes a page thin.',
+    }),
+});
+/**
+ * The overview tile's three numbers, over a window **the caller names**.
+ *
+ * `since_ms` rather than "today": which day that is, only the browser knows. A
+ * cloud that picks its own day boundary shows a developer in another timezone a
+ * number they cannot reproduce. Echoed back so a rendered tile can say which
+ * window it is describing.
+ */
+/**
+ * `GET /api/org/jobs/summary`'s query: the window, and nothing else.
+ *
+ * **`since_ms` is required and has no default.** Which day "today" is, only
+ * the browser knows; a cloud that picked its own boundary would show a
+ * developer in another timezone a number they cannot reproduce from anything
+ * in front of them. The absence of a default is the contract here, not an
+ * omission — see `jobRunSummary`, which echoes the window back so a rendered
+ * tile can say what it is describing.
+ *
+ * Its own shape rather than a slice of `jobRunQuery`: pagination and filters
+ * mean nothing to an aggregate, and `.strict()` would refuse them anyway, so
+ * borrowing that schema would advertise seven parameters the route ignores.
+ *
+ * `.strict()` for `jobRunQuery`'s reason — a mistyped `since_mss` that is
+ * silently ignored answers `200` over a window nobody chose, which is worse
+ * than a refusal because it looks like data.
+ */
+export const jobRunSummaryQuery = z.object({ since_ms: wireTimestampMs }).strict();
+export const jobRunSummary = z.object({
+    running: z.number().int().nonnegative(),
+    started: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    since_ms: z.number().int().nonnegative(),
+});

package/dist/mcp.d.ts

@@ -0,0 +1,239 @@
+import { z } from 'zod';
+/**
+ * The MCP server of §17: **one** remote MCP endpoint for the whole platform,
+ * whose tools are the exposed services and datapoints the signed-in user's
+ * roles permit. The per-app `/mcp/<identifier>` servers this file once
+ * described were deleted by the org-central identity redesign (D5/D6).
+ *
+ * **This file describes the seam, not the protocol.** The MCP messages
+ * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
+ * Model Context Protocol and implemented with its official SDK — writing our
+ * own zod copies of them would create a second source of truth for somebody
+ * else's specification, which is the one thing this package exists to avoid.
+ * What lives here is what *Fleetless* decides: which revision we speak, where
+ * the endpoint is, how a tool is named, and what the console is shown before
+ * an end user ever connects.
+ */
+/**
+ * The protocol revision W7c speaks. Chosen with André on 2026-08-18 over the
+ * newer `2026-07-28`.
+ *
+ * This is the latest revision the **stable** MCP TypeScript SDK ships, and it
+ * negotiates down to `2024-11-05`, so it covers the AI tools that exist today.
+ * `2026-07-28` is real and is where the protocol is going — it *removes*
+ * Streamable HTTP's session ids, the standalone SSE channel and resumability,
+ * and servers speaking only it answer `405` to GET and DELETE.
+ *
+ * **Which is why this server is stateless anyway.** Building sessions we would
+ * have to delete again is work in the wrong direction, and a per-process
+ * session map is the assumption that breaks at the second cloud instance —
+ * the register already carries one row of exactly that shape
+ * (`max_realtime_connections`), and W8 is where a second instance appears.
+ */
+export declare const MCP_PROTOCOL_VERSION: "2025-11-25";
+/**
+ * The path of the **central** MCP server — what a *Fleetless user* pastes into
+ * their AI tool, appended to the cloud's public base URL.
+ *
+ * **Not parameterised, and that is now a statement rather than the absence of
+ * one.** The central endpoint serves the org's team with the console tool
+ * family (2026-09-05, D7); an app's users reach a different endpoint, whose
+ * path `mcpAppEndpointPath` builds. Two constants for two audiences, so a call
+ * site says which it means instead of an argument deciding it.
+ *
+ * **The canonical URL is `<PUBLIC_API_BASE_URL>${MCP_ENDPOINT_PATH}`, not the
+ * friendly alias.** `mcp.fleetless.dev` is a reverse proxy onto the same
+ * cloud, but the cloud mints every OAuth issuer, resource and `aud` from
+ * `PUBLIC_API_BASE_URL` and compares the token's `aud` against that string —
+ * never against the request's `Host`. Hand out the canonical one.
+ */
+export declare const MCP_ENDPOINT_PATH: "/mcp";
+/**
+ * The path of **one app's** MCP server (D7) — what an app user pastes into
+ * their AI tool, served only while the app's `appAuthConfig.mcp_enabled` is on.
+ *
+ * A helper rather than a template literal at four call sites, for
+ * `OAUTH_PATHS`' reason: the console shows this string with a copy button, the
+ * cloud registers the route from it, and the docs render it. A path spelled in
+ * three places is a path two of them will one day spell differently — and this
+ * repository has already paid for exactly that, with an `idpStart` entry naming
+ * a route the cloud had deleted.
+ *
+ * **This is the path, not the URL.** Append it to `PUBLIC_API_BASE_URL`, the
+ * canonical origin the cloud mints every issuer and audience from, rather than
+ * to the friendly `mcp.fleetless.dev` alias — a token's `aud` is compared
+ * against the canonical string and never against the request's `Host`.
+ *
+ * There was a `mcpEndpointPath(appIdentifier)` before, deleted with the per-app
+ * endpoint in the central-MCP cut and remembered here because the shape of that
+ * mistake is worth not repeating: the console kept offering a copy button for a
+ * URL that answered `404`. This one exists **with** its endpoint, and the
+ * cloud's route-manifest test is what keeps them together.
+ */
+export declare function mcpAppEndpointPath(appIdentifier: string): string;
+/**
+ * **Every path one app's MCP server answers on, built from its identifier
+ * once** (D7).
+ *
+ * Six strings, and each of them is spelled in at least three places that
+ * cannot see one another: the cloud registers the route, the console renders a
+ * copy button beside it, the reverse proxy in front of `mcp.fleetless.dev`
+ * routes on it, and the documentation site prints it. `mcpAppEndpointPath`
+ * already made that argument for the endpoint alone; the five paths around it
+ * are worse to get wrong, because an MCP client **discovers** them — it reads
+ * the two metadata documents and follows what they say — so a divergence is
+ * not a `404` a developer sees, it is a sign-in that stops halfway in somebody
+ * else's client.
+ *
+ * **The two `.well-known` paths are not ours to choose.** RFC 9728 §3.1 and
+ * RFC 8414 §3 both say the same thing: take the resource (or issuer) URL, and
+ * insert `/.well-known/<document>` *before* its path component. The resource
+ * here is `<base>/mcp/<identifier>`, so the documents are at
+ * `<base>/.well-known/oauth-protected-resource/mcp/<identifier>` — the app
+ * identifier last, not `…/oauth-protected-resource/<identifier>`, which is the
+ * spelling the design note used in prose and which no conforming client would
+ * ever fetch. Writing them here is what keeps that reading from being made
+ * twice.
+ *
+ * **These are paths, not URLs.** Append them to `PUBLIC_API_BASE_URL`, for the
+ * reason `mcpAppEndpointPath` states: the cloud mints every issuer, resource
+ * and `aud` from the canonical base and compares a token's `aud` against that
+ * string, never against the request's `Host`. The friendly alias is a proxy in
+ * front of the same cloud, and a URL built on it hands a client an audience
+ * the token endpoint will refuse.
+ *
+ * Named in the shape `OAUTH_PATHS` had, and deliberately a **function** rather
+ * than the object that constant was: there is one set of these per app, and a
+ * frozen object would have to be built at a call site that knows the
+ * identifier anyway. The lesson kept from `OAUTH_PATHS` is the other one — it
+ * stood for months with an entry naming a route the cloud had deleted — so
+ * `routes.ts` builds its manifest rows *from this function*, passing
+ * `':appIdentifier'`, and the cloud's route-manifest test holds the registered
+ * routes to the manifest. A path that stops existing cannot stay spelled here.
+ */
+export interface McpAppPaths {
+    /** The Streamable HTTP transport itself: `POST` carries JSON-RPC, `GET` and `DELETE` are the stateless transport's `405`. */
+    readonly endpoint: string;
+    /** RFC 9728 protected-resource metadata for the endpoint. */
+    readonly protectedResourceMetadata: string;
+    /** RFC 8414 authorization-server metadata; this app's MCP server is its own authorization server. */
+    readonly authorizationServerMetadata: string;
+    /** RFC 7591 dynamic client registration, per app. */
+    readonly register: string;
+    /** The authorization endpoint, which redirects to the app's own `mcp_login_url` rather than rendering a page. */
+    readonly authorize: string;
+    /** The token endpoint; `authorization_code` with PKCE and nothing else. */
+    readonly token: string;
+}
+export declare function MCP_APP_PATHS(appIdentifier: string): McpAppPaths;
+/**
+ * Which exposed kind a tool came from. Not the MCP protocol's vocabulary —
+ * ours, so the console can group a preview the way the services editor is
+ * grouped.
+ */
+export declare const mcpToolKind: z.ZodEnum<{
+    datapoint: "datapoint";
+    action: "action";
+    service: "service";
+    publisher: "publisher";
+    camera: "camera";
+}>;
+export type McpToolKind = z.infer<typeof mcpToolKind>;
+/** MCP's own bound on a tool name, and the charset that is safe across clients. */
+export declare const MCP_TOOL_NAME_MAX = 128;
+export declare const mcpToolNamePattern: RegExp;
+/**
+ * One exposure of a robot, as `robot_describe` and the console's per-role
+ * preview list it (FL-006). Every exposure the role grants is listed —
+ * a missing `description` is shown as `null`, never used to hide the entry.
+ *
+ * `input_schema` is a JSON Schema document generated from an action's,
+ * service's or publisher's `parameters`; `null` for the other kinds. It is
+ * `unknown` for the same reason the retired `mcpToolPreview.input_schema`
+ * was: pinning it would mean maintaining a zod description of JSON Schema.
+ */
+export declare const mcpExposure: z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        datapoint: "datapoint";
+        action: "action";
+        service: "service";
+        publisher: "publisher";
+        camera: "camera";
+    }>;
+    description: z.ZodNullable<z.ZodString>;
+    unit: z.ZodNullable<z.ZodString>;
+    decimals: z.ZodNullable<z.ZodNumber>;
+    input_schema: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strip>;
+export type McpExposure = z.infer<typeof mcpExposure>;
+/** The two role capabilities a robot tool can need beyond a slug grant. `presence` is a stream and has no tool. */
+export declare const mcpCapabilities: z.ZodObject<{
+    action_history: z.ZodBoolean;
+    assets: z.ZodBoolean;
+}, z.core.$strip>;
+export type McpCapabilities = z.infer<typeof mcpCapabilities>;
+/** What one caller may do on one robot — the answer to `robot_describe`. */
+export declare const mcpRobotDatasheet: z.ZodObject<{
+    robot_id: z.ZodUUID;
+    robot_name: z.ZodString;
+    capabilities: z.ZodObject<{
+        action_history: z.ZodBoolean;
+        assets: z.ZodBoolean;
+    }, z.core.$strip>;
+    exposures: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        kind: z.ZodEnum<{
+            datapoint: "datapoint";
+            action: "action";
+            service: "service";
+            publisher: "publisher";
+            camera: "camera";
+        }>;
+        description: z.ZodNullable<z.ZodString>;
+        unit: z.ZodNullable<z.ZodString>;
+        decimals: z.ZodNullable<z.ZodNumber>;
+        input_schema: z.ZodNullable<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type McpRobotDatasheet = z.infer<typeof mcpRobotDatasheet>;
+/**
+ * What a developer sees before an end user connects: the datasheet each
+ * robot of the app would answer for one role. Replaces the per-slug tool
+ * preview and its `omitted` list — with a fixed catalog there is no tool to
+ * omit, only exposures to grant.
+ */
+export declare const mcpRolePreviewResponse: z.ZodObject<{
+    role_id: z.ZodUUID;
+    robots: z.ZodArray<z.ZodObject<{
+        robot_id: z.ZodUUID;
+        robot_name: z.ZodString;
+        capabilities: z.ZodObject<{
+            action_history: z.ZodBoolean;
+            assets: z.ZodBoolean;
+        }, z.core.$strip>;
+        exposures: z.ZodArray<z.ZodObject<{
+            slug: z.ZodString;
+            kind: z.ZodEnum<{
+                datapoint: "datapoint";
+                action: "action";
+                service: "service";
+                publisher: "publisher";
+                camera: "camera";
+            }>;
+            description: z.ZodNullable<z.ZodString>;
+            unit: z.ZodNullable<z.ZodString>;
+            decimals: z.ZodNullable<z.ZodNumber>;
+            input_schema: z.ZodNullable<z.ZodUnknown>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type McpRolePreviewResponse = z.infer<typeof mcpRolePreviewResponse>;
+/**
+ * Where a signed asset link is served. An MCP session token is refused on
+ * REST by design, so `asset_get`/`urdf_get` mint a bearer-free link the agent
+ * behind the client can fetch. Lifetime is fixed; the token binds robot, asset
+ * and expiry under `JWT_SECRET`.
+ */
+export declare const MCP_ASSET_LINK_PATH: "/api/asset-links";
+export declare const MCP_ASSET_LINK_TTL_MS: number;