@exponential_app/engine 0.0.0-stage → 0.1.0

package/dist/types/emcp/fixtures/hub.json

@@ -0,0 +1,498 @@
+{
+  "$comment": "EXP-1507 (eMCP local hub, epic EXP-1503, 2026-10-31): ONE LOOPBACK ENDPOINT OVER SEVERAL MCP SERVERS, the device-side twin of `/api/mcp/apps`. A hub MOUNTS servers under a name (`serverNamePattern`: lowercase letters, digits and `-`, starting with a letter or digit, at most `serverNameMax`; never `__`, the separator), each an upstream MCP server (Streamable HTTP, the run's headers resolved) or an in-process tool provider; mounting a name twice replaces it. NAMING: the hub lists a mounted tool as exposes.json's qualified name with the SERVER NAME in place of the app slug (`qualifiedToolName(server, tool)`, `<server>__<tool>`, cut + hashed past 64) and resolves a call with `splitToolName` against the run's own list, so a tool whose own name holds `__` is never listed; servers are listed sorted by name and a qualified name an earlier server holds is dropped (`listToolNames`; within a server its own order). GRANTS (`listCases`): the hub admits a RUN with its own bearer token (an earlier token of the run dies; a revoke kills it) and a GRANT: `servers` = server name -> level (`read` | `write`; a server not named = `none`), plus the `teamId` and `userId` the run acts for (null on a device with no team). A tool's access is exposes.json's `upstreamAccess(annotations)` (read iff `readOnlyHint: true`, else write: destructive tools need write like every other); a tool is LISTED and CALLABLE iff access.json's `toolVisible(level, access)`. A CALL (`callCases`) to a name not on the run's list answers MCP's unknown-tool error (JSON-RPC -32602), never a hint that it exists, and is audited `denied` with error `unknownTool`; a listed call reaches its server once, as `tool` with the arguments as received. AUDIT: EVERY tools/call, denied ones included, writes ONE `mcp_calls` row (audit.json's columns, handed to the host's sink after the call, never blocking it): `id` a fresh uuid, `team_id` / `user_id` = the grant's, `client_id` = the run's session id (on a device the run is the client), `app_id` null, `tool` = the name as called, `status` = audit.json's `callStatus` of the outcome, `error` = `errors[outcome]` (null for `ok` and `isError`), `latency_ms` = the hub's wall time rounded down, `args_hash` = audit.json's `argsHash` of the arguments as received, `created_at` = ISO-8601 UTC with milliseconds. Outcomes (`outcomes`): `ok` = a result; `isError` = a result with `isError: true` -> failed; `invalidParams` = the server answered JSON-RPC -32602 -> invalid; `rpcError` = any other JSON-RPC error, `unreachable` = no connection or an HTTP error, `timeout` = no answer in time -> upstream; `unknown` = not listed for the run -> denied. Retention is the host's (audit.json `retentionDays`).",
+  "serverNamePattern": "^[a-z0-9][a-z0-9-]*$",
+  "serverNameMax": 32,
+  "outcomes": {
+    "ok": "ok",
+    "isError": "failed",
+    "invalidParams": "invalid",
+    "rpcError": "upstream",
+    "unreachable": "upstream",
+    "timeout": "upstream",
+    "unknown": "denied"
+  },
+  "errors": {
+    "ok": null,
+    "isError": null,
+    "invalidParams": "invalidArguments",
+    "rpcError": "upstreamFailed",
+    "unreachable": "upstreamFailed",
+    "timeout": "upstreamTimeout",
+    "unknown": "unknownTool"
+  },
+  "unknownToolCode": -32602,
+  "serverNameCases": [
+    {
+      "name": "files",
+      "expected": true
+    },
+    {
+      "name": "my-server-2",
+      "expected": true
+    },
+    {
+      "name": "2fa",
+      "expected": true
+    },
+    {
+      "name": "",
+      "expected": false
+    },
+    {
+      "name": "Files",
+      "expected": false
+    },
+    {
+      "name": "my_server",
+      "expected": false
+    },
+    {
+      "name": "a__b",
+      "expected": false
+    },
+    {
+      "name": "-lead",
+      "expected": false
+    },
+    {
+      "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "expected": false
+    },
+    {
+      "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "expected": true
+    }
+  ],
+  "servers": [
+    {
+      "name": "files",
+      "tools": [
+        {
+          "name": "read_file",
+          "annotations": {
+            "readOnlyHint": true
+          }
+        },
+        {
+          "name": "write_file"
+        },
+        {
+          "name": "delete_file",
+          "annotations": {
+            "destructiveHint": true
+          }
+        }
+      ]
+    },
+    {
+      "name": "computer",
+      "tools": [
+        {
+          "name": "screenshot",
+          "annotations": {
+            "readOnlyHint": true
+          }
+        },
+        {
+          "name": "click",
+          "annotations": {
+            "readOnlyHint": false
+          }
+        },
+        {
+          "name": "bad__name",
+          "annotations": {
+            "readOnlyHint": true
+          }
+        }
+      ]
+    },
+    {
+      "name": "linear",
+      "tools": [
+        {
+          "name": "list_issues",
+          "annotations": {
+            "readOnlyHint": true
+          }
+        }
+      ]
+    }
+  ],
+  "listCases": [
+    {
+      "name": "write on files, read on computer, nothing on linear",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "expected": [
+        "computer__screenshot",
+        "files__read_file",
+        "files__write_file",
+        "files__delete_file"
+      ]
+    },
+    {
+      "name": "no grant lists nothing",
+      "grant": {
+        "servers": {},
+        "teamId": null,
+        "userId": null
+      },
+      "expected": []
+    },
+    {
+      "name": "read everywhere lists only read-only tools",
+      "grant": {
+        "servers": {
+          "files": "read",
+          "computer": "read",
+          "linear": "read"
+        },
+        "teamId": null,
+        "userId": null
+      },
+      "expected": [
+        "computer__screenshot",
+        "files__read_file",
+        "linear__list_issues"
+      ]
+    },
+    {
+      "name": "an unknown server in the grant lists nothing extra",
+      "grant": {
+        "servers": {
+          "ghost": "write"
+        },
+        "teamId": null,
+        "userId": null
+      },
+      "expected": []
+    }
+  ],
+  "callCases": [
+    {
+      "name": "a granted read tool answers",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "run": "run-1",
+      "call": {
+        "name": "files__read_file",
+        "arguments": {
+          "path": "/tmp/a"
+        }
+      },
+      "upstream": "ok",
+      "expected": {
+        "routed": {
+          "server": "files",
+          "tool": "read_file"
+        },
+        "row": {
+          "teamId": "t1",
+          "userId": "u1",
+          "clientId": "run-1",
+          "appId": null,
+          "tool": "files__read_file",
+          "status": "ok",
+          "error": null,
+          "argsHash": "sha256:15df809ad5fadb66f0b31bafc206dcfe620d8da8767fb76e41d3603a45dc870d"
+        }
+      }
+    },
+    {
+      "name": "a granted write tool that errors is failed",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "run": "run-1",
+      "call": {
+        "name": "files__write_file",
+        "arguments": {
+          "path": "/tmp/a",
+          "text": "x"
+        }
+      },
+      "upstream": "isError",
+      "expected": {
+        "routed": {
+          "server": "files",
+          "tool": "write_file"
+        },
+        "row": {
+          "teamId": "t1",
+          "userId": "u1",
+          "clientId": "run-1",
+          "appId": null,
+          "tool": "files__write_file",
+          "status": "failed",
+          "error": null,
+          "argsHash": "sha256:a835aef067e005a76bff09fcbb9b3706400153a45f58557f82d0a2ed10d24357"
+        }
+      }
+    },
+    {
+      "name": "a write tool on a read grant is unknown",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "run": "run-1",
+      "call": {
+        "name": "computer__click",
+        "arguments": {
+          "x": 1,
+          "y": 2
+        }
+      },
+      "upstream": null,
+      "expected": {
+        "routed": null,
+        "row": {
+          "teamId": "t1",
+          "userId": "u1",
+          "clientId": "run-1",
+          "appId": null,
+          "tool": "computer__click",
+          "status": "denied",
+          "error": "unknownTool",
+          "argsHash": "sha256:689a8f1db95402580476e38c264278ce7b1e664320cfb4e9ae8d3a908cf09964"
+        }
+      }
+    },
+    {
+      "name": "a server outside the grant is unknown",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "run": "run-1",
+      "call": {
+        "name": "linear__list_issues",
+        "arguments": null
+      },
+      "upstream": null,
+      "expected": {
+        "routed": null,
+        "row": {
+          "teamId": "t1",
+          "userId": "u1",
+          "clientId": "run-1",
+          "appId": null,
+          "tool": "linear__list_issues",
+          "status": "denied",
+          "error": "unknownTool",
+          "argsHash": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
+        }
+      }
+    },
+    {
+      "name": "a name that is no tool is unknown",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "run": "run-1",
+      "call": {
+        "name": "exponential_issues",
+        "arguments": {
+          "op": "get"
+        }
+      },
+      "upstream": null,
+      "expected": {
+        "routed": null,
+        "row": {
+          "teamId": "t1",
+          "userId": "u1",
+          "clientId": "run-1",
+          "appId": null,
+          "tool": "exponential_issues",
+          "status": "denied",
+          "error": "unknownTool",
+          "argsHash": "sha256:9947f251d5afe097024f2fda1a3628ca26263332cc01f991c32fbee174509b5e"
+        }
+      }
+    },
+    {
+      "name": "arguments the server refuses are invalid",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "run": "run-1",
+      "call": {
+        "name": "files__read_file",
+        "arguments": {
+          "path": 3
+        }
+      },
+      "upstream": "invalidParams",
+      "expected": {
+        "routed": {
+          "server": "files",
+          "tool": "read_file"
+        },
+        "row": {
+          "teamId": "t1",
+          "userId": "u1",
+          "clientId": "run-1",
+          "appId": null,
+          "tool": "files__read_file",
+          "status": "invalid",
+          "error": "invalidArguments",
+          "argsHash": "sha256:e68a0cd06893b799b492d46c161213bb510a98800fa5ae27ee9ee86893a67a2c"
+        }
+      }
+    },
+    {
+      "name": "an unreachable server is upstream",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "run": "run-1",
+      "call": {
+        "name": "computer__screenshot",
+        "arguments": {}
+      },
+      "upstream": "unreachable",
+      "expected": {
+        "routed": {
+          "server": "computer",
+          "tool": "screenshot"
+        },
+        "row": {
+          "teamId": "t1",
+          "userId": "u1",
+          "clientId": "run-1",
+          "appId": null,
+          "tool": "computer__screenshot",
+          "status": "upstream",
+          "error": "upstreamFailed",
+          "argsHash": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
+        }
+      }
+    },
+    {
+      "name": "a server that never answers is upstream",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "run": "run-1",
+      "call": {
+        "name": "files__delete_file",
+        "arguments": {
+          "path": "/tmp/a"
+        }
+      },
+      "upstream": "timeout",
+      "expected": {
+        "routed": {
+          "server": "files",
+          "tool": "delete_file"
+        },
+        "row": {
+          "teamId": "t1",
+          "userId": "u1",
+          "clientId": "run-1",
+          "appId": null,
+          "tool": "files__delete_file",
+          "status": "upstream",
+          "error": "upstreamTimeout",
+          "argsHash": "sha256:15df809ad5fadb66f0b31bafc206dcfe620d8da8767fb76e41d3603a45dc870d"
+        }
+      }
+    },
+    {
+      "name": "another rpc error is upstream",
+      "grant": {
+        "servers": {
+          "files": "write",
+          "computer": "read"
+        },
+        "teamId": "t1",
+        "userId": "u1"
+      },
+      "run": "run-1",
+      "call": {
+        "name": "files__read_file",
+        "arguments": {
+          "path": "/tmp/b"
+        }
+      },
+      "upstream": "rpcError",
+      "expected": {
+        "routed": {
+          "server": "files",
+          "tool": "read_file"
+        },
+        "row": {
+          "teamId": "t1",
+          "userId": "u1",
+          "clientId": "run-1",
+          "appId": null,
+          "tool": "files__read_file",
+          "status": "upstream",
+          "error": "upstreamFailed",
+          "argsHash": "sha256:e877f6ab58c441e61056d01fc02073f833cbf957e2849be594f33996e10be718"
+        }
+      }
+    }
+  ],
+  "createdAtCases": [
+    {
+      "ms": 0,
+      "expected": "1970-01-01T00:00:00.000Z"
+    },
+    {
+      "ms": 1793491200123,
+      "expected": "2026-11-01T00:00:00.123Z"
+    },
+    {
+      "ms": 951782400000,
+      "expected": "2000-02-29T00:00:00.000Z"
+    }
+  ]
+}

package/dist/types/emcp/src/access.d.ts

@@ -0,0 +1,55 @@
+import type { ToolAccess } from "./exposes.js";
+export declare const GRANT_KINDS: readonly GrantKind[];
+export declare const GRANT_ACCESS: readonly GrantAccess[];
+export declare const POLICY_LEVELS: readonly Level[];
+export type GrantKind = `builtin` | `apps`;
+/** The consent page's Read only | Full. */
+export type GrantAccess = `read` | `full`;
+export type Level = `none` | `read` | `write`;
+/** The `mcp_grants` columns this contract reads. */
+export interface Grant {
+    kind: GrantKind;
+    allTeams: boolean;
+    teamIds: readonly string[];
+    boardIds: readonly string[];
+    allApps: boolean;
+    appIds: readonly string[];
+    access: GrantAccess;
+}
+/** A grant's access as a level (`full` = `write`). */
+export declare function grantLevel(access: GrantAccess): Level;
+/** Every reason a grant row is malformed (empty = valid). */
+export declare function grantErrors(grant: Grant): string[];
+/** The member's policy for an app (the Settings › MCP Access table); no
+ *  row = `write`. */
+export declare function memberPolicy(row: Level | null | undefined): Level;
+export interface AccessInput {
+    grant: Grant;
+    /** The app's id and team. */
+    appId: string;
+    teamId: string;
+    /** The app is trashed. */
+    appDeleted: boolean;
+    /** The caller's role in the app's team, null = not a member. */
+    role: string | null;
+    /** The caller's policy row for this app, null = none. */
+    policy: Level | null;
+}
+/** Effective access to one app = grant ∩ the member's policy; `none` for
+ *  an app the grant does not cover, a trashed app, a non-member or a
+ *  malformed grant. */
+export declare function effectiveAccess(input: AccessInput): Level;
+/** May a caller with `level` see (and call) a tool of `access`? A read
+ *  token never sees a write tool. */
+export declare function toolVisible(level: Level, access: ToolAccess): boolean;
+export interface AssistantScopeInput {
+    /** The member's hidden personal team (the Assistant's own conversation). */
+    personalTeamId: string;
+    /** The teams the member belongs to now, in their order. */
+    memberTeamIds: readonly string[];
+    /** The composer's Teams pick on the conversation root; null = every team. */
+    pickedTeamIds: readonly string[] | null;
+}
+/** #EXP-1720: the teams an Assistant tree may touch this turn: the
+ *  personal team, then the picked teams ∩ the member's (null = all). */
+export declare function assistantScope(input: AssistantScopeInput): string[];

package/dist/types/emcp/src/audit.d.ts

@@ -0,0 +1,22 @@
+export declare const CALL_STATUSES: readonly CallStatus[];
+export declare const AUDIT_RETENTION_DAYS: number;
+export type CallStatus = `ok` | `denied` | `invalid` | `failed` | `upstream`;
+export { canonicalJson } from "./pure.js";
+/** The row's `args_hash`: `sha256:` + the hex SHA-256 of the canonical
+ *  JSON of the call's arguments (none = `{}`). Never the arguments. */
+export declare function argsHash(args: unknown): string;
+export interface CallOutcome {
+    /** The tool was not listed for the caller, or a call-time check refused. */
+    denied?: boolean;
+    /** The arguments failed the tool's input schema. */
+    invalid?: boolean;
+    /** The upstream answered an error or could not be reached. */
+    upstreamError?: boolean;
+    /** The run itself failed (the result is an error). */
+    error?: boolean;
+}
+/** The row's `status`, first match wins: denied, invalid, upstream,
+ *  failed, ok. */
+export declare function callStatus(outcome: CallOutcome): CallStatus;
+/** Is a row created at `createdAt` past retention at `now` (ISO times)? */
+export declare function auditExpired(createdAt: string, now: string): boolean;

package/dist/types/emcp/src/automations.d.ts

@@ -0,0 +1,111 @@
+import fixture from "../fixtures/automations.json" with { type: "json" };
+import { type Expose, type ExposeRun } from "./exposes.js";
+export declare const AUTOMATIONS_LIMITS: {
+    namePattern: string;
+    nameMax: number;
+    maxAutomations: number;
+    minScheduleGapMinutes: number;
+    eventPattern: string;
+    eventMax: number;
+    runsPerMinute: number;
+    clientPrefix: string;
+};
+export declare const AUTOMATION_ERRORS: readonly string[];
+export type AutomationTrigger = {
+    schedule: {
+        cron: string;
+        tz?: string;
+    };
+} | {
+    record: {
+        kind: string;
+        op: `create` | `update` | `delete`;
+    };
+} | {
+    event: string;
+} | {
+    webhook: {
+        name: string;
+    };
+};
+export interface Automation {
+    name: string;
+    on: AutomationTrigger;
+    run: ExposeRun;
+    /** A member's email; default = the publisher (`resolveSponsor`). */
+    sponsor?: string;
+}
+export type TriggerKind = `schedule` | `record` | `event` | `webhook`;
+export interface AutomationError {
+    index: number | null;
+    code: string;
+}
+export interface AutomationContext {
+    kinds: readonly string[];
+    upstreams: readonly string[];
+}
+/** The kind of an automation's `on` (exactly one key), else null. */
+export declare function triggerKind(on: unknown): TriggerKind | null;
+/** One cron field's values (`*`, lists, ranges, steps; digits only), or null. */
+export declare function cronFieldValues(raw: string, min: number, max: number): number[] | null;
+/** A schedule's check: null = fine, else `schedule` | `scheduleTooOften`.
+ *  The gap = the smallest distance between the minutes of a day it fires
+ *  on (minute × hour, circular over the day). */
+export declare function scheduleError(schedule: unknown): `schedule` | `scheduleTooOften` | null;
+/** Every `${…}` of a value is a root the trigger carries (`templateRoots`):
+ *  `record.<path>`, `event.<path>`, `firedAt`. */
+export declare function templatesValid(value: unknown, kind: TriggerKind): boolean;
+/** Rewrites `${record.…}`, `${event.…}`, `${firedAt}` to exposes'
+ *  `${input.<root>…}`, so `resolveArgs` fills them. */
+export declare function toInputTemplates<T>(value: T): T;
+/** The run with its templates filled from the trigger's input
+ *  `{record?, event?, firedAt}`. */
+export declare function resolveAutomationRun(run: ExposeRun, input: Record<string, unknown>): ExposeRun;
+/** The run as an exposes binding (the broker runs it like a tool). */
+export declare function automationExpose(automation: Pick<Automation, `name` | `run`>): Expose;
+/** Every error of an app's `automations`, in order (empty = valid). */
+export declare function validateAutomations(list: unknown, ctx: AutomationContext): AutomationError[];
+/** The trigger a record write, an event or a webhook delivery is, for
+ *  `matchAutomations`; `byAgent` = the slug of the agent whose session
+ *  tree caused it. */
+export type FiredBy = ({
+    record: {
+        kind: string;
+        op: string;
+    };
+} | {
+    event: string;
+} | {
+    webhook: string;
+}) & {
+    byAgent?: string | null;
+};
+/** The automations a record write or event fires, in package order. LOOP
+ *  GUARD: a write or event caused by an automation run fires nothing; one
+ *  caused from an agent's tree (`byAgent`) fires no hand-off to that agent. */
+export declare function matchAutomations(list: unknown, firedBy: FiredBy, fromAutomation: boolean): string[];
+export interface SponsorMember {
+    id: string;
+    email: string;
+    role: string;
+    /** The member's app access (`none` | `read` | `write`). */
+    level: string;
+}
+export type SponsorState = (typeof fixture.sponsorStates)[number];
+export type SponsorResult = {
+    userId: string;
+} | {
+    paused: SponsorState;
+};
+/** C23: who an automation acts as, or why it is paused. */
+export declare function resolveSponsor(input: {
+    declared: string | null | undefined;
+    publishedBy: string | null | undefined;
+    members: readonly SponsorMember[];
+}): SponsorResult;
+/** Whether another run may start (the app's runs of the last 60 s). */
+export declare function rateAllows(runsLastMinute: number): boolean;
+/** The audit row's `client_id`. */
+export declare function automationClientId(name: string): string;
+/** The audit row's `tool`. */
+export declare function automationTool(run: ExposeRun): string;