@exponential_app/engine 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,242 @@
+export declare const EXPOSES_LIMITS: {
+    namePattern: string;
+    nameMax: number;
+    titleMax: number;
+    descriptionMax: number;
+    maxTools: number;
+    separator: string;
+    toolNameMax: number;
+    slugHashLength: number;
+};
+export declare const EXPOSES_ERRORS: string[];
+export declare const PROVENANCE_KEYS: {
+    app: string;
+    tool: string;
+    via: string;
+    upstream: string;
+    device: string;
+};
+export type ToolAccess = `read` | `write`;
+export type RecordsRun = {
+    records: {
+        op: `list` | `get` | `upsert`;
+        kind: string;
+        id?: unknown;
+        /** An object = jsonb containment; a list = the Q1 query's conditions. */
+        where?: Record<string, unknown> | unknown[];
+        data?: Record<string, unknown>;
+        limit?: unknown;
+        /** #VAPP-216: a list may name one of the package's `queries`, and may
+         *  carry any Q1 JSON query key (sort, sum, group, aggregate, running,
+         *  before, mine, user, month) beside `where` and `limit`. */
+        query?: string;
+        [key: string]: unknown;
+    };
+};
+export type ActionRun = {
+    action: string;
+    args?: Record<string, unknown>;
+};
+export type UpstreamRun = {
+    upstream: string;
+    tool: string;
+    args?: Record<string, unknown>;
+};
+/** #VAPP-236 (A2): hand judgement to a team agent (`agent` = its slug). */
+export type AgentRun = {
+    agent: string;
+    prompt: string;
+    device?: string;
+};
+export type ExposeRun = RecordsRun | ActionRun | UpstreamRun | AgentRun;
+export interface Expose {
+    name: string;
+    title: string;
+    description: string;
+    /** A JSON Schema of `type: "object"`. */
+    input: {
+        type: `object`;
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    access: ToolAccess;
+    run: ExposeRun;
+}
+/** What the app's package declares beside its `exposes`. */
+export interface ExposeContext {
+    /** The record kinds of the manifest (`records: {<kind>: …}`). */
+    kinds: readonly string[];
+    /** The team MCP server names the app declares (`upstreams`): an app sees
+     *  only its own. */
+    upstreams: readonly string[];
+}
+export type RunVia = `records` | `action` | `upstream` | `agent`;
+export declare function runVia(run: ExposeRun): RunVia;
+/** #VAPP-236 (A2): the agent hand-off's limits (exposes.json `agent`). */
+export declare const AGENT_RUN: {
+    slugPattern: string;
+    slugMax: number;
+    promptMax: number;
+    devices: string[];
+    runsPerMinute: number;
+    valueMax: number;
+    dataMax: number;
+    auditPrefix: string;
+    agentSlugCases: {
+        name: string;
+        expected: string;
+    }[];
+    agentRateCases: {
+        handoffsLastMinute: number;
+        allowed: boolean;
+    }[];
+    promptCutCase: {
+        template: string;
+        repeat: number;
+        value: string;
+        valueRepeat: number;
+        promptLength: number;
+        endsWith: string;
+    };
+    briefCases: ({
+        name: string;
+        brief: {
+            prompt: string;
+            input: {
+                record: {
+                    id: string;
+                    title: string;
+                    hours: number;
+                };
+                firedAt: string;
+                note?: undefined;
+                t?: undefined;
+            };
+            app: {
+                name: string;
+                slug: string;
+            };
+            source: string;
+            ref: {
+                kind: string;
+                id: string;
+            };
+        };
+        expected: string;
+    } | {
+        name: string;
+        brief: {
+            prompt: string;
+            input: {
+                note: string;
+                record?: undefined;
+                firedAt?: undefined;
+                t?: undefined;
+            };
+            app: {
+                name: string;
+                slug: string;
+            };
+            source: string;
+            ref?: undefined;
+        };
+        expected: string;
+    } | {
+        name: string;
+        brief: {
+            prompt: string;
+            input: {
+                t: string;
+                record?: undefined;
+                firedAt?: undefined;
+                note?: undefined;
+            };
+            app: {
+                name: string;
+                slug: string;
+            };
+            source: string;
+            ref?: undefined;
+        };
+        expected: string;
+    })[];
+};
+/** An agent's slug: its name lower-cased, every run of characters outside
+ *  ASCII `a-z0-9` one `-`, dashes trimmed, cut to `slugMax`. */
+export declare function agentSlug(name: string): string;
+/** Whether another hand-off may start (the app's hand-offs of the last 60 s). */
+export declare function agentRateAllows(handoffsLastMinute: number): boolean;
+/** The audit row's `tool` of a hand-off. */
+export declare function agentAuditTool(slug: string): string;
+export interface AgentBriefInput {
+    prompt: string;
+    input: Record<string, unknown>;
+    app: {
+        name: string;
+        slug: string;
+    };
+    /** `automation <name>`, `tool <name>`, `handoff <name>`. */
+    source: string;
+    ref?: {
+        kind: string;
+        id: string;
+    } | null;
+}
+/** The hand-off's message: the frozen prompt (its templates filled as
+ *  inline data), then the input as a fenced data block. Data is never
+ *  instructions (§12.1). */
+export declare function agentBrief(brief: AgentBriefInput): string;
+/** An `exponential_<noun>_<op>` action is a read when the last word of its
+ *  op is a read word (`list`, `get`, …); a verb tool is a write. */
+export declare function actionAccess(name: string): ToolAccess;
+export { upstreamDestructive, type UpstreamAnnotations } from "./pure.js";
+import { type UpstreamAnnotations } from "./pure.js";
+/** An upstream tool reads only when it says so (`readOnlyHint: true`). */
+export declare function upstreamAccess(annotations: UpstreamAnnotations | null | undefined): ToolAccess;
+/** The input paths a value's templates name (`${input.a.b}` → `a.b`). */
+export declare function templatePaths(value: unknown): string[];
+/** Fill a binding's args from the call's input. A string that is exactly
+ *  one template takes the value itself (its type kept); an absent value
+ *  drops the object key and is null in an array. A template inside other
+ *  text is replaced by the value as text (absent/null = empty, objects =
+ *  compact JSON). Everything else is copied. */
+export declare function resolveArgs(template: unknown, input: Record<string, unknown>): unknown;
+export interface ExposeError {
+    /** The binding's index in `exposes`, null for the list itself. */
+    index: number | null;
+    code: string;
+}
+/** Every error of an app's `exposes`, in order (empty = valid). */
+export declare function validateExposes(exposes: readonly Expose[], ctx: ExposeContext): ExposeError[];
+/** The call-time check of an upstream binding against the upstream tool's
+ *  live annotations: null = callable, else the error code. */
+export declare function upstreamCallError(expose: Expose, annotations: UpstreamAnnotations | null | undefined): string | null;
+/** `n` lowercase base32 characters of the SHA-256 of `text`. */
+export declare function shortHash(text: string, n?: number): string;
+/** The MCP name of an app's tool: `<slug>__<name>`. Longer than
+ *  `toolNameMax`, the slug is cut and ends in `-<hash of the full slug>`
+ *  so the name stays unique and stable. */
+export declare function qualifiedToolName(slug: string, name: string): string;
+/** `<slug>__<name>` back to its parts (the first `__` splits: a binding
+ *  name never holds one); null for anything else. */
+export declare function splitToolName(qualified: string): {
+    app: string;
+    tool: string;
+} | null;
+export interface ListedApp {
+    slug: string;
+    exposes: readonly {
+        name: string;
+    }[];
+}
+/** The tool names of several apps on one endpoint, apps sorted by slug. A
+ *  name an earlier app already holds is dropped (only a cut slug can
+ *  collide). */
+export declare function listToolNames(apps: readonly ListedApp[]): {
+    app: string;
+    tool: string;
+    name: string;
+}[];
+/** The `_meta` every result of an app tool carries (provenance: which app
+ *  and binding answered, and through what). */
+export declare function provenanceMeta(slug: string, expose: Expose): Record<string, string>;

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

@@ -0,0 +1,63 @@
+import fixture from "../fixtures/hub.json" with { type: "json" };
+import { type Level } from "./access.js";
+import { type CallStatus } from "./audit.js";
+import { type UpstreamAnnotations } from "./exposes.js";
+export type HubOutcome = keyof typeof fixture.outcomes;
+/** What a run may reach: a level per mounted server (not named = none). */
+export interface HubGrant {
+    servers: Record<string, Exclude<Level, `none`>>;
+    teamId: string | null;
+    userId: string | null;
+}
+export interface HubTool {
+    name: string;
+    annotations?: UpstreamAnnotations | null;
+}
+export interface HubServer {
+    name: string;
+    tools: readonly HubTool[];
+}
+export interface HubRoute {
+    server: string;
+    tool: string;
+}
+/** May a server be mounted under `name`? */
+export declare function hubServerNameValid(name: string): boolean;
+/** The run's tools/list: every tool its grant lets it see, qualified. */
+export declare function hubToolList(grant: HubGrant, servers: readonly HubServer[]): {
+    app: string;
+    tool: string;
+    name: string;
+}[];
+/** Where a call goes: a name on the run's own list, else null (unknown). */
+export declare function hubRoute(grant: HubGrant, servers: readonly HubServer[], name: string): HubRoute | null;
+/** The row's status and error code for an outcome. */
+export declare function hubOutcomeStatus(outcome: HubOutcome): {
+    status: CallStatus;
+    error: string | null;
+};
+export interface HubAuditRow {
+    id: string;
+    teamId: string | null;
+    userId: string | null;
+    clientId: string;
+    appId: null;
+    tool: string;
+    status: CallStatus;
+    error: string | null;
+    latencyMs: number;
+    argsHash: string;
+    createdAt: string;
+}
+/** The `mcp_calls` row of one hub call (`outcome` = `unknown` when it was
+ *  not routed). */
+export declare function hubAuditRow(input: {
+    id: string;
+    grant: HubGrant;
+    run: string;
+    name: string;
+    args: unknown;
+    outcome: HubOutcome;
+    latencyMs: number;
+    createdAtMs: number;
+}): HubAuditRow;

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

@@ -0,0 +1,7 @@
+export * from "./exposes.js";
+export * from "./access.js";
+export * from "./audit.js";
+export * from "./vault.js";
+export * from "./upstream.js";
+export * from "./hub.js";
+export * from "./automations.js";

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

@@ -0,0 +1,11 @@
+/** Canonical JSON: object keys sorted by code point, recursively, no
+ *  whitespace; `undefined` object members dropped; -0 prints as 0. */
+export declare function canonicalJson(value: unknown): string;
+/** The MCP annotations of an upstream tool (from its `tools/list`). */
+export interface UpstreamAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+}
+/** An upstream tool is destructive when it says so (`destructiveHint:
+ *  true`) or a word of its name is a destructive word. */
+export declare function upstreamDestructive(tool: string, annotations: UpstreamAnnotations | null | undefined): boolean;

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

@@ -0,0 +1,288 @@
+export declare const UPSTREAM_STATES: readonly UpstreamState[];
+export declare const UPSTREAM_LABELS: Record<UpstreamState, string>;
+export declare const UPSTREAM_ERRORS: {
+    disconnected: string;
+    missing: string;
+    failed: string;
+};
+export type UpstreamState = `disconnected` | `connecting` | `connected` | `expired` | `reconnect` | `failed`;
+export type UpstreamEvent = `connect` | `callbackOk` | `callbackError` | `flowExpired` | `secretSet` | `expire` | `refreshOk` | `refreshFailed` | `unauthorized` | `disconnect` | `serverChanged`;
+/** The next state; an event a state does not list changes nothing. */
+export declare function upstreamStep(state: UpstreamState, event: UpstreamEvent): UpstreamState;
+/** May the broker call through it (an expired token is refreshed first)? */
+export declare function upstreamCallable(state: UpstreamState): boolean;
+/** The upstreams the consent page offers to connect: every server the
+ *  chosen apps declare whose member state is not callable (no state =
+ *  `disconnected`), sorted, each once. A server that no longer exists is
+ *  not offered (its bindings answer `upstreamMissing`). */
+export declare function missingUpstreams(declared: readonly (readonly string[])[], states: Readonly<Record<string, UpstreamState>>, servers: readonly string[]): string[];
+export declare const UPSTREAM_MAPPING: {
+    $comment: string;
+    resolveCases: ({
+        name: string;
+        upstream: string;
+        bound: null;
+        servers: {
+            id: string;
+            name: string;
+        }[];
+        expected: {
+            id: string;
+            source: string;
+        };
+    } | {
+        name: string;
+        upstream: string;
+        bound: string;
+        servers: {
+            id: string;
+            name: string;
+        }[];
+        expected: {
+            id: string;
+            source: string;
+        };
+    } | {
+        name: string;
+        upstream: string;
+        bound: null;
+        servers: {
+            id: string;
+            name: string;
+        }[];
+        expected: null;
+    })[];
+    writeCases: ({
+        name: string;
+        upstream: string;
+        serverId: string;
+        servers: {
+            id: string;
+            name: string;
+        }[];
+        expected: {
+            op: string;
+            serverId: string;
+            error?: undefined;
+        };
+    } | {
+        name: string;
+        upstream: string;
+        serverId: null;
+        servers: {
+            id: string;
+            name: string;
+        }[];
+        expected: {
+            op: string;
+            serverId?: undefined;
+            error?: undefined;
+        };
+    } | {
+        name: string;
+        upstream: string;
+        serverId: string;
+        servers: {
+            id: string;
+            name: string;
+        }[];
+        expected: {
+            op: string;
+            serverId?: undefined;
+            error?: undefined;
+        };
+    } | {
+        name: string;
+        upstream: string;
+        serverId: string;
+        servers: {
+            id: string;
+            name: string;
+        }[];
+        expected: {
+            error: string;
+            op?: undefined;
+            serverId?: undefined;
+        };
+    })[];
+    auditCases: ({
+        upstream: string;
+        server: string;
+        expected: string;
+    } | {
+        upstream: string;
+        server: null;
+        expected: string;
+    })[];
+};
+export interface UpstreamServerRef {
+    id: string;
+    name: string;
+}
+export type UpstreamResolution<T> = {
+    server: T;
+    source: `mapped` | `name`;
+};
+/** The team server filling a declared upstream: a binding on the team, else
+ *  the server of exactly that name, else null. */
+export declare function resolveUpstreamServer<T extends UpstreamServerRef>(upstream: string, bound: string | null, servers: readonly T[]): UpstreamResolution<T> | null;
+export type UpstreamMappingWrite = {
+    op: `set`;
+    serverId: string;
+} | {
+    op: `clear`;
+} | {
+    error: string;
+};
+/** What an owner's pick writes: the exact-name default keeps no row. */
+export declare function upstreamMappingWrite(upstream: string, serverId: string | null, servers: readonly UpstreamServerRef[]): UpstreamMappingWrite;
+/** The audit row's `tool` for a mapping change. */
+export declare function upstreamMappingTool(upstream: string, server: string | null): string;
+export declare const UPSTREAM_BINDING: {
+    readonly scheme: string;
+    readonly cacheSeconds: number;
+    readonly banner: string;
+    readonly connect: string;
+    readonly errors: {
+        notReadOnly: string;
+        destructive: string;
+        notDeclared: string;
+        invalid: string;
+    };
+};
+export interface UpstreamBinding {
+    server: string;
+    tool: string;
+    args: Record<string, unknown>;
+}
+/** A param's text as an argument: JSON literals, numbers, objects and
+ *  arrays read as JSON; anything else stays the string. */
+export declare function upstreamArg(text: string): unknown;
+/** `upstream:crm/search?q=acme` → `{server: "crm", tool: "search", args:
+ *  {q: "acme"}}` (eUI's source grammar; the name splits at its LAST `/`),
+ *  null when it is not an upstream source. */
+export declare function parseUpstreamSource(source: string): UpstreamBinding | null;
+/** Exponential's install check: every `upstream:` source of a package's
+ *  template bindings parses and names one of its `upstreams`. */
+export declare function upstreamDeclareIssues(sources: readonly string[], upstreams: readonly string[]): {
+    index: number;
+    code: string;
+}[];
+/** The broker's call-time check against the tool's live annotations and the
+ *  package's `sources` (an exact `upstream:<server>/<tool>` vouches for a
+ *  tool that sets no readOnlyHint): null = it reads, else the error. */
+export declare function upstreamReadError(binding: Pick<UpstreamBinding, `server` | `tool`>, annotations: {
+    readOnlyHint?: unknown;
+    destructiveHint?: unknown;
+} | null | undefined, sources: readonly string[]): string | null;
+/** The cache key of one read: member, server id, tool and canonical args. */
+export declare function upstreamCacheKey(member: string, serverId: string, tool: string, args: Record<string, unknown>): string;
+/** An MCP tools/call result as the binding's value. */
+export declare function upstreamBindingValue(result: Record<string, unknown>): {
+    value: unknown;
+} | {
+    error: string;
+};
+/** One host answer of `apps.upstreamRead`. */
+export type UpstreamReadAnswer = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+    server: string;
+    offline?: string;
+};
+/** The host's banners: one per server whose read answered
+ *  upstreamDisconnected, sorted, each once. */
+export declare function upstreamBanners(answers: readonly UpstreamReadAnswer[]): string[];
+export declare const UPSTREAM_DEVICE: {
+    readonly ttlSeconds: number;
+    readonly answerTimeoutMs: number;
+    readonly maxAnswerBytes: number;
+    readonly errors: {
+        notOwner: string;
+        noDevice: string;
+        offline: string;
+        noAnswer: string;
+    };
+    readonly copy: {
+        noDevice: string;
+        notOwner: string;
+        offline: string;
+        noAnswer: string;
+    };
+};
+/** A server row as the router reads it: its transport and the device it
+ *  names (with the device's owner and label), if any. */
+export interface RoutedServer {
+    name: string;
+    transport: string;
+    device: {
+        id: string;
+        ownerId: string;
+        label: string;
+    } | null;
+}
+export type UpstreamRoute = {
+    route: `server`;
+} | {
+    route: `device`;
+    deviceId: string;
+} | {
+    error: string;
+    message: string;
+};
+/** Where one call to `server` by `callerId` (the member, or an automation's
+ *  sponsor) runs: the server, the owner's device, or a refusal. */
+export declare function upstreamRoute(server: RoutedServer, callerId: string): UpstreamRoute;
+/** What the relay answered `POST /devices/:userId/:deviceId/upstream` with. */
+export type DeviceRelayOutcome = {
+    delivered: true;
+} | {
+    delivered: false;
+    reason: string;
+};
+/** The device's (opened) answer: the tool's result, or why it did not run. */
+export type DeviceAnswer = {
+    ok: true;
+    result: Record<string, unknown>;
+} | {
+    ok: false;
+    reason: `vetoed` | `refused` | `failed`;
+    error: string;
+};
+export type DeviceCallOutcome = {
+    result: Record<string, unknown>;
+} | {
+    error: string;
+    message: string;
+    offline?: string;
+};
+/** One device call's outcome for the broker. `answer` = null when the relay
+ *  delivered nothing that opens. */
+export declare function deviceCallOutcome(server: string, deviceLabel: string, relay: DeviceRelayOutcome, answer: DeviceAnswer | null): DeviceCallOutcome;
+/** Whether a device may claim a call: the member's own, on that device,
+ *  unexpired (`expiresAt` ms) and not claimed yet. */
+export declare function deviceCallClaimable(call: {
+    userId: string;
+    deviceId: string;
+    expiresAt: number;
+    claimed: boolean;
+}, claim: {
+    userId: string;
+    deviceId: string;
+}, now: number): boolean;
+/** One host banner: its text and whether it carries the Connect action. */
+export interface UpstreamHostBanner {
+    server: string;
+    text: string;
+    connect: boolean;
+}
+/** The host's banners ×4: `Connect <server>` for an upstreamDisconnected
+ *  read, the offline copy for a device that is offline; one per server,
+ *  sorted by server. */
+export declare function upstreamHostBanners(answers: readonly UpstreamReadAnswer[]): UpstreamHostBanner[];
+/** A server row's URL rule: https anywhere; http on loopback or a LAN host
+ *  (a device-routed server's reach). */
+export declare function mcpUrlAllowed(value: string): boolean;

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

@@ -0,0 +1,34 @@
+export declare const VAULT_VERSION: string;
+export interface VaultKey {
+    kid: string;
+    key: Buffer;
+}
+/** The current key and the retired ones (decrypt only). */
+export interface Keyring {
+    current: VaultKey;
+    retired: readonly VaultKey[];
+}
+/** `<kid>:<base64 of 32 bytes>` → the key; null for anything else. */
+export declare function parseVaultKey(spec: string | null | undefined): VaultKey | null;
+/** `VAULT_KEY` + `VAULT_KEYS_RETIRED` (comma-separated) → the keyring;
+ *  null when the current key is missing or malformed, or a kid repeats. A
+ *  malformed retired entry is null too: a typo must not lose a key. */
+export declare function parseKeyring(current: string | null | undefined, retired: string | null | undefined): Keyring | null;
+/** The additional data binding a value to its row and the key that sealed
+ *  it: `ev1|<kid>|<table>.<column>|<row id>`. */
+export declare function vaultAad(kid: string, table: string, column: string, rowId: string): string;
+export interface VaultSlot {
+    table: string;
+    column: string;
+    rowId: string;
+}
+/** Seal with an explicit iv (the vectors); `vaultSeal` draws one. */
+export declare function vaultSealWith(key: VaultKey, iv: Buffer, plaintext: string, slot: VaultSlot): string;
+export declare function vaultSeal(keyring: Keyring, plaintext: string, slot: VaultSlot): string;
+/** The kid a value was sealed with; null for anything not a vault value. */
+export declare function vaultKid(value: string | null | undefined): string | null;
+/** The plaintext, or null for anything that does not open: another
+ *  version, an unknown kid, another slot, a tampered value. */
+export declare function vaultOpen(keyring: Keyring, value: string | null | undefined, slot: VaultSlot): string | null;
+/** A value sealed with a retired key: the rotation sweep re-seals it. */
+export declare function vaultNeedsRotation(keyring: Keyring, value: string | null | undefined): boolean;