@exponential_app/engine 0.0.0-stage → 0.1.1

package/dist/types/eengine/src/broker.d.ts

@@ -0,0 +1,80 @@
+import { type BrokerAuditRow, type BrokerVerdict, type CallFrom, type Grants, type GrantValue, type ManifestEntry } from "./capabilities.js";
+import { type ConsentAnswer, type GrantVia, type SurfaceComponent } from "./consent.js";
+import { type BlobStore, type McpCallResult, type NativeCapability } from "./tools.js";
+/** A refusal or a failure (eCore's shape: a code + a message). */
+export interface Failure {
+    code: string;
+    message: string;
+}
+/** Where secrets live (Keychain, Keystore, libsecret; the web: IndexedDB). */
+export interface Vault {
+    read(key: string): Promise<string | null>;
+    write(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** Where the broker's audit rows go. */
+export interface CallAudit {
+    record(row: BrokerAuditRow): void;
+}
+/** The ask sheet the person answers (consent.json `consentSheet`): a genUI surface. */
+export interface ConsentSheet {
+    scope: string;
+    components: SurfaceComponent[];
+    data: Record<string, unknown>;
+}
+/** What a brokered call answers. */
+export type BrokerAnswer = {
+    result: McpCallResult;
+}
+/** The person decides first: paint the sheet, then `answer`. */
+ | {
+    ask: BrokerVerdict;
+    sheet: ConsentSheet;
+}
+/** `code` = `UNKNOWN_TOOL` for unknown, else `FORBIDDEN`; `message` = the reason. */
+ | {
+    refused: Failure;
+};
+export interface BrokerSetup {
+    appId: string;
+    appName: string;
+    signer: string;
+    manifest: readonly ManifestEntry[];
+    grants: Grants;
+    capabilities: readonly NativeCapability[];
+    vault: Vault;
+    /** The app's files: what capabilities read (`fileId`) and store. */
+    blobs: BlobStore;
+    /** The package's screen names (a notification's tap opens one). */
+    screens: readonly string[];
+    audit?: CallAudit | null;
+}
+/** One app instance's broker. */
+export declare class Broker {
+    private readonly setup;
+    private grantsNow;
+    private foreground;
+    /** The last grants write (tests and a closing page await it). */
+    persisted: Promise<void>;
+    constructor(setup: BrokerSetup);
+    get appId(): string;
+    get manifest(): readonly ManifestEntry[];
+    get capabilities(): readonly NativeCapability[];
+    grants(): Grants;
+    /** The lifecycle tells the broker whether a sheet may show. */
+    setForeground(foreground: boolean): void;
+    private provided;
+    private record;
+    private run;
+    /** One call from app UI (`client` = null) or an agent run (`client` = its run id). */
+    call(from: CallFrom, client: string | null, name: string, args: unknown): Promise<BrokerAnswer>;
+    /** The person's answer to the sheet for `verdict` (an Ask): store it per
+     *  consent.json, then run or refuse the call. The answer is the gesture. */
+    answer(from: CallFrom, client: string | null, name: string, args: unknown, verdict: BrokerVerdict, answer: ConsentAnswer): Promise<BrokerAnswer>;
+    /** Change a grant (the Permissions sheet's Switch). Only the ConsentUi
+     *  after a gesture; `value` null = revoke. Answers consent.json's refusal, or null. */
+    setGrant(via: GrantVia, gesture: boolean, scope: string, value: GrantValue | null): string | null;
+    /** The Permissions sheet (consent.json `manageSheet`). */
+    permissionsSheet(): SurfaceComponent[];
+    private persist;
+}

package/dist/types/eengine/src/capabilities.d.ts

@@ -0,0 +1,88 @@
+import { type CallStatus, type HubOutcome } from "../../emcp/src/index.js";
+export type ConsentKind = `ask` | `picker`;
+export type GrantValue = `granted` | `denied`;
+export type Grants = Record<string, GrantValue>;
+export type CallFrom = `ui` | `agent`;
+export interface CapabilityScope {
+    id: string;
+    verb: string;
+    consent: ConsentKind;
+    tools: readonly string[];
+    hostOnly?: boolean;
+    origins?: boolean;
+}
+export interface CapabilityDef {
+    name: string;
+    label: string;
+    scopes: readonly CapabilityScope[];
+    /** #VAPP-273: a capability one host alone provides (`ede`); every other host answers `unavailable`. */
+    host?: string;
+}
+/** One entry of a package's capability manifest (format 5 `capabilities`). */
+export interface ManifestEntry {
+    id: string;
+    why: string;
+    origins?: readonly string[];
+}
+export declare const CAPABILITIES: readonly CapabilityDef[];
+export declare const RESERVED_CAPABILITY_NAMES: readonly string[];
+/** Is `id` a scope id of the right form (`<capability>.<scope>`)? */
+export declare const scopeIdValid: (id: string) => boolean;
+/** May a capability be mounted under `name`? A hub server name that is not reserved. */
+export declare const capabilityNameValid: (name: string) => boolean;
+export declare const capabilityDef: (name: string) => CapabilityDef | null;
+/** The catalog scope with `id`, with its capability. */
+export declare function scopeDef(id: string): {
+    capability: CapabilityDef;
+    scope: CapabilityScope;
+} | null;
+/** A call's name → `{capability, tool}`: `<capability>__<tool>` from an agent,
+ *  `<capability>_<tool>` from app UI (round 9 §6.3: split at the first `_`); null for any other form or a reserved name. */
+export declare function parseCapabilityCall(from: CallFrom, name: string): {
+    capability: string;
+    tool: string;
+} | null;
+export type BrokerVerdictKind = `call` | `ask` | `denied` | `unknown` | `unavailable`;
+export interface BrokerVerdict {
+    verdict: BrokerVerdictKind;
+    capability: string | null;
+    tool: string | null;
+    scope: string | null;
+    reason: string | null;
+}
+export interface BrokerCall {
+    from: CallFrom;
+    name: string;
+    arguments?: unknown;
+}
+export interface BrokerInput {
+    manifest: readonly ManifestEntry[];
+    grants: Grants;
+    /** The capability names this host mounts. */
+    provided: readonly string[];
+    foreground: boolean;
+    call: BrokerCall;
+}
+/** An `https://host[:port]` origin of a URL, or null. */
+export declare function urlOrigin(url: unknown): string | null;
+/** The broker's verdict for one call (capabilities.json `decideCases`). */
+export declare function brokerDecide(input: BrokerInput): BrokerVerdict;
+/** An agent's tools/list: every tool of a declared, provided, non-host-only scope. */
+export declare function agentToolList(manifest: readonly ManifestEntry[], provided: readonly string[]): string[];
+export interface BrokerAuditRow {
+    appId: string;
+    clientId: string;
+    tool: string;
+    status: CallStatus;
+    error: string | null;
+    argsHash: string;
+}
+/** The audit row of one brokered call. `client` = the agent run's id (null for UI);
+ *  `outcome` = the call's outcome when it ran (`verdict: call`), else ignored. */
+export declare function brokerAuditRow(input: {
+    appId: string;
+    client: string | null;
+    call: BrokerCall;
+    verdict: BrokerVerdict;
+    outcome: HubOutcome | null;
+}): BrokerAuditRow;

package/dist/types/eengine/src/consent.d.ts

@@ -0,0 +1,50 @@
+import { type BrokerVerdictKind, type Grants, type GrantValue, type ManifestEntry } from "./capabilities.js";
+export type ConsentAnswer = `allow` | `once` | `deny` | `dismiss`;
+export type GrantVia = `consentUi` | `agent` | `hubTool` | `package` | `hostConfig` | `sync`;
+export declare const CONSENT_COPY: {
+    title: string;
+    options: {
+        label: string;
+        value: string;
+    }[];
+    confirm: string;
+    manageTitle: string;
+};
+export declare const GRANTS_RECORD_VERSION: number;
+/** A genUI component (the flat A2UI list a surface carries). */
+export type SurfaceComponent = Record<string, unknown> & {
+    id: string;
+    component: string;
+};
+/** The sheet's answer → the call's verdict and the grants to store. */
+export declare function consentAnswer(grants: Grants, scope: string, answer: ConsentAnswer): {
+    verdict: BrokerVerdictKind;
+    reason: string | null;
+    grants: Grants;
+};
+/** A grant write: only the ConsentUi, only after a gesture, only an ask scope. */
+export declare function grantWrite(manifest: readonly ManifestEntry[], grants: Grants, write: {
+    via: GrantVia;
+    gesture: boolean;
+    scope: string;
+    value: GrantValue | null;
+}): {
+    grants: Grants;
+    refused: string | null;
+};
+/** The Vault key and canonical JSON value of an app's grants. */
+export declare function grantsRecord(app: string, signer: string, manifest: readonly ManifestEntry[], grants: Grants): {
+    key: string;
+    value: string;
+};
+/** The grants that survive a package load (`stored` = the Vault value, or null). */
+export declare function grantsOnPackage(stored: string | null, signer: string, manifest: readonly ManifestEntry[]): Grants;
+/** The ask sheet for one manifest entry: the surface's components and data. */
+export declare function consentSheet(app: string, entry: ManifestEntry): {
+    components: SurfaceComponent[];
+    data: {
+        answer: ConsentAnswer;
+    };
+};
+/** The Permissions sheet: one Switch per declared ask scope, in manifest order. */
+export declare function manageSheet(manifest: readonly ManifestEntry[], grants: Grants): SurfaceComponent[];

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

@@ -0,0 +1,12 @@
+export * from "./capabilities.js";
+export * from "./consent.js";
+export * from "./lifecycle.js";
+export * from "./providers.js";
+export * from "./outbox.js";
+export * from "./tools.js";
+export * from "./pdf.js";
+export * from "./runner.js";
+export * from "./broker.js";
+export * from "./stores.js";
+export * from "./instance.js";
+export * from "./synced.js";

package/dist/types/eengine/src/instance.d.ts

@@ -0,0 +1,131 @@
+import { type PackageIssue, type RecordsValue } from "@exponential_app/eui/host";
+import { Broker, type CallAudit, type ConsentSheet, type Failure, type Vault } from "./broker.js";
+import type { BrokerVerdict, Grants, GrantValue, ManifestEntry } from "./capabilities.js";
+import { type ConsentAnswer, type GrantVia, type SurfaceComponent } from "./consent.js";
+import { type LifecycleEffect, type LifecycleEvent, type LifecycleState } from "./lifecycle.js";
+import { type OutboxCall, type OutboxEntry, type OutboxResult } from "./outbox.js";
+import { type EngineIdentity, type NetworkPolicy } from "./providers.js";
+import type { EngineRecordStore, WriteBatch } from "./stores.js";
+import type { BlobStore, NativeCapability } from "./tools.js";
+export type Presentation = `replace` | `push` | `sheet`;
+/** Maps screens to windows (desktop), nav stacks and sheets (phones), the page (the web). */
+export interface WindowHost {
+    open(app: string, screen: string, params: Record<string, string>, how: Presentation): void;
+}
+/** An optional transport to an authority; absent = the store is the authority, no outbox. */
+export interface SyncTransport {
+    push(app: string, call: OutboxCall, input: Record<string, unknown>): Promise<OutboxResult>;
+    /** `push` with the server's answer, for a call that awaits its own entry. */
+    send?(app: string, call: OutboxCall, input: Record<string, unknown>): Promise<Pushed>;
+}
+/** One replay as a transport answers it. */
+export interface Pushed {
+    result: OutboxResult;
+    answer?: unknown;
+    message?: string;
+    invalid?: boolean;
+}
+/** What a host hands the Engine (providers.json; no telemetry or update key: none exists). */
+export interface EngineHostConfig {
+    host: {
+        kind: string;
+        platform: string;
+        formFactor: string;
+        locale: string;
+    };
+    storage: EngineRecordStore;
+    blobs: BlobStore;
+    identity: EngineIdentity;
+    vault: Vault;
+    window: WindowHost;
+    /** ISO 8601 UTC with milliseconds (tests pin it). */
+    clock?: () => string;
+    network: NetworkPolicy;
+    sync?: SyncTransport | null;
+    capabilities: readonly NativeCapability[];
+    audit?: CallAudit | null;
+    newId?: () => string;
+}
+/** Why a package could not load: `signature` (signed, does not verify) or `invalid` (genUI refuses it). */
+export declare class LoadError extends Error {
+    readonly kind: `signature` | `invalid`;
+    readonly issues: PackageIssue[];
+    constructor(kind: `signature` | `invalid`, issues: PackageIssue[]);
+}
+/** What a host function call answers. */
+export type CallResult = {
+    value: unknown;
+}
+/** The person decides first: paint the sheet, then `answerConsent` with the same call. */
+ | {
+    ask: BrokerVerdict;
+    sheet: ConsentSheet;
+}
+/** Refused (the failed-action toast's reason). */
+ | {
+    refused: Failure;
+};
+/** Where the instance keeps its last screen (lifecycle.json `persist`). */
+export declare const screenKey: (app: string) => string;
+type Pkg = Record<string, unknown> & {
+    id?: unknown;
+    name?: unknown;
+    records?: unknown;
+    capabilities?: unknown;
+    screens?: unknown;
+};
+/** The package a file carries (`package`), or the value itself when it is a bare package. */
+export declare const packageOf: (file: unknown) => unknown;
+/** One running app. */
+export declare class AppInstance {
+    private readonly config;
+    readonly pkg: Pkg;
+    readonly appId: string;
+    readonly signer: string | null;
+    readonly broker: Broker;
+    private stateNow;
+    private outboxNow;
+    private lastScreen;
+    private constructor();
+    /** Load a package file (or a bare package): verify its signature when it
+     *  carries one, validate the package, reconcile its grants. */
+    static load(config: EngineHostConfig, file: unknown): Promise<AppInstance>;
+    get manifest(): readonly ManifestEntry[];
+    grants(): Grants;
+    get state(): LifecycleState;
+    /** The outbox entries still pending or acked (queue mode). */
+    get outbox(): readonly OutboxEntry[];
+    get mode(): `queue` | `direct`;
+    private me;
+    private now;
+    /** The person answered the sheet of an Ask for this call (the answer is the gesture). */
+    answerConsent(name: string, args: unknown, verdict: BrokerVerdict, answer: ConsentAnswer): Promise<CallResult>;
+    /** The Permissions sheet's Switch: only the ConsentUi, after a gesture. Answers the refusal, or null. */
+    setGrant(via: GrantVia, gesture: boolean, scope: string, value: GrantValue | null): string | null;
+    /** The Permissions sheet (a genUI surface). */
+    permissionsSheet(): SurfaceComponent[];
+    /** One lifecycle event: the next state, with its effects carried out
+     *  (open → the WindowHost, persist → the Vault, flush → the outbox).
+     *  Answers the effects (sources and automations are the host's). */
+    event(event: LifecycleEvent): Promise<LifecycleEffect[]>;
+    /** A `records:<kind>?…` source's value (genUI's records query over the
+     *  store's rows with the outbox laid over them); undefined = not a records source. */
+    recordsValue(source: string): Promise<RecordsValue | null | undefined>;
+    /** Called with every change to the app's rows (re-resolve the bound sources). */
+    subscribe(on: () => void): () => void;
+    /** A host function call from the app's UI: `records_upsert` /
+     *  `records_delete` / `records_batch`, `app_navigate`, or a capability
+     *  (`<capability>.<tool>`, through the broker). `newIds` = the client ids of
+     *  its creates, in order. */
+    call(name: string, args: unknown, newIds?: readonly string[]): Promise<CallResult>;
+    /** The kind policy check for a write, as the identity sees it. */
+    private refusal;
+    private write;
+    /** Flush the outbox through the sync provider (FIFO, a retry stops it). */
+    flush(): Promise<void>;
+}
+/** An outbox entry as one store batch. */
+export declare function batchOf(entry: OutboxEntry): WriteBatch;
+/** How many client ids a call's creates take (the runner generates them). */
+export declare function createsOf(name: string, args: unknown): number;
+export {};

package/dist/types/eengine/src/lifecycle.d.ts

@@ -0,0 +1,64 @@
+export type LifecyclePhase = `stopped` | `foreground` | `background`;
+export interface LifecycleState {
+    phase: LifecyclePhase;
+    screen: string | null;
+    params: Record<string, string> | null;
+}
+export type LifecycleEvent = {
+    type: `launch`;
+} | {
+    type: `foreground`;
+} | {
+    type: `background`;
+} | {
+    type: `terminate`;
+} | {
+    type: `online`;
+} | {
+    type: `deepLink`;
+    screen?: string | null;
+    params?: Record<string, unknown> | null;
+} | {
+    type: `notificationTap`;
+    app: string;
+    screen?: string | null;
+    params?: Record<string, unknown> | null;
+};
+export type LifecycleEffect = {
+    effect: `open`;
+    screen: string;
+    params: Record<string, string>;
+} | {
+    effect: `flush`;
+} | {
+    effect: `sources`;
+    live: boolean;
+} | {
+    effect: `automations`;
+    on: boolean;
+} | {
+    effect: `persist`;
+    screen: string;
+    params: Record<string, string>;
+} | {
+    effect: `refused`;
+    reason: string;
+};
+export interface LifecyclePackage {
+    id: string;
+    screens?: unknown;
+}
+export interface LifecycleContext {
+    pkg: LifecyclePackage;
+    /** The screen the instance persisted last (null = none). */
+    lastScreen: {
+        screen: string;
+        params: Record<string, unknown>;
+    } | null;
+}
+export declare const STOPPED: LifecycleState;
+/** One lifecycle event → the next state and its effects, in order. */
+export declare function lifecycleStep(state: LifecycleState, event: LifecycleEvent, cx: LifecycleContext): {
+    state: LifecycleState;
+    effects: LifecycleEffect[];
+};

package/dist/types/eengine/src/outbox.d.ts

@@ -0,0 +1,3 @@
+export { outboxFlush, outboxOutcome, outboxPendingLabel, outboxPrune, outboxReflected, outboxRequest, outboxRows, outboxVerb, outboxWrites, type OutboxCall, type OutboxEntry, type OutboxOutcome, type OutboxResult, type OutboxWrite, } from "../../domain-contract/src/app-records.js";
+/** A host with a sync provider queues every app write; one without writes through. */
+export declare const outboxMode: (hasSync: boolean) => `queue` | `direct`;

package/dist/types/eengine/src/pdf.d.ts

@@ -0,0 +1,36 @@
+export type PdfBlock = {
+    heading: string;
+} | {
+    text: string;
+} | {
+    image: string;
+    caption?: string;
+} | {
+    pageBreak: true;
+};
+export interface PdfArguments {
+    title: string;
+    name?: string;
+    blocks: readonly PdfBlock[];
+}
+export type PdfResult = {
+    bytes: Uint8Array;
+    pages: number;
+} | {
+    error: string;
+};
+/** A paragraph per `\n`, words on runs of spaces, greedy; a too-wide word breaks at its longest fitting prefix. */
+export declare function wrapLines(text: string, font: `F1` | `F2`, size: number): number[][];
+/** A number rounded to 2 decimals, shortest form (`12`, `12.5`, `-0.25`). */
+export declare function pdfNumber(x: number): string;
+interface PdfImage {
+    width: number;
+    height: number;
+    dict: string;
+    data: Uint8Array;
+}
+/** A JPEG or a supported PNG → its XObject, else null. */
+export declare function pdfImage(bytes: Uint8Array): PdfImage | null;
+/** Lays out and writes the document. `getBlob` resolves an app file id. */
+export declare function renderPdf(args: PdfArguments, getBlob: (id: string) => Promise<Uint8Array | null>): Promise<PdfResult>;
+export {};

package/dist/types/eengine/src/providers.d.ts

@@ -0,0 +1,38 @@
+import { type RecordOp, type RecordOwnership, type RecordPolicy, type RecordViewer } from "@exponential_app/eui/host";
+import fixture from "../fixtures/providers.json" with { type: "json" };
+export type ProviderKey = keyof typeof fixture.providers;
+export type NetworkPolicy = `off` | `upstreamsOnly` | `any`;
+export type IdentityKind = `member` | `local` | `peer`;
+export type AgentProviderId = `acp` | `localModel` | `remoteSession`;
+export declare const PROVIDER_KEYS: ProviderKey[];
+export declare const FORBIDDEN_HOST_KEYS: readonly string[];
+export declare const NETWORK_POLICIES: readonly NetworkPolicy[];
+export declare const IDENTITY_KINDS: readonly IdentityKind[];
+export declare const AGENT_PROVIDERS: readonly AgentProviderId[];
+export interface HostConfigIssue {
+    key: string;
+    code: `missing` | `forbidden` | `unknown` | `invalid` | `duplicateAgent` | `duplicateCapability` | `invalidCapability`;
+}
+/** Every problem with a host config: providers in order, then forbidden/unknown keys sorted. */
+export declare function validateHostConfig(config: Record<string, unknown>): HostConfigIssue[];
+export type EngineIdentity = {
+    kind: `member`;
+    userId: string;
+    role: string | null;
+    access?: `none` | `read` | `write`;
+} | {
+    kind: `local`;
+    deviceId: string;
+} | {
+    kind: `peer`;
+    key: string;
+};
+/** The records viewer of an identity: local = the one owner of everything ("me"). */
+export declare function engineViewer(identity: EngineIdentity): Required<RecordViewer>;
+/** Why the viewer of `identity` may not `op` (null = allowed). */
+export declare const engineRecordRefusal: (identity: EngineIdentity, policy: RecordPolicy, op: RecordOp, row?: RecordOwnership | null) => string | null;
+/** May the instance reach `target` under `policy`? `declared` = the package declares the upstream (or the origin). */
+export declare function networkAllows(policy: NetworkPolicy, target: `upstream` | `sync` | `http`, declared: boolean): {
+    allowed: boolean;
+    reason: string | null;
+};

package/dist/types/eengine/src/runner.d.ts

@@ -0,0 +1,82 @@
+import type { SurfaceComponent } from "./consent.js";
+import type { NetworkPolicy } from "./providers.js";
+export declare const RUNNER_COPY: {
+    permissions: string;
+    failed: {
+        title: string;
+        missing: string;
+        config: string;
+        signature: string;
+        invalid: string;
+        busy: string;
+    };
+    refusals: {
+        consentDenied: string;
+        consentDismissed: string;
+        consentNeeded: string;
+        notDeclared: string;
+        originNotDeclared: string;
+        unavailable: string;
+        offline: string;
+        network: string;
+    };
+};
+export declare const RUNNER_BUNDLE: {
+    dir: string;
+    files: {
+        package: string;
+        config: string;
+    };
+    locations: {
+        macos: string;
+        windows: string;
+        linux: string;
+        android: string;
+        ios: string;
+        web: string;
+    };
+};
+export declare const RUNNER_SHELL: {
+    sidebarWidth: number;
+    titleLevel: string;
+    permissionsIcon: string;
+    failureIcon: string;
+};
+export type FormFactor = `wide` | `compact`;
+export type RunnerFailure = `missing` | `config` | `signature` | `invalid` | `busy`;
+/** A bundle's `runner.json`, validated. */
+export interface RunnerConfig {
+    id: string;
+    name: string;
+    version: string;
+    network: NetworkPolicy;
+}
+export interface RunnerConfigIssue {
+    key: string;
+    code: string;
+}
+/** `runner.json` → the config (absent optional keys = their default) and its issues, in key order then the extra keys sorted. */
+export declare function runnerConfig(input: unknown): {
+    config: RunnerConfig | null;
+    issues: RunnerConfigIssue[];
+};
+type Pkg = Record<string, unknown> & {
+    name?: unknown;
+    templates?: unknown;
+    screens?: unknown;
+    capabilities?: unknown;
+};
+/** Does the package declare an `ask` scope (the shell then offers Permissions)? */
+export declare function runnerHasPermissions(pkg: Pkg): boolean;
+/**
+ * The package the runner's painter installs: every screen's template wrapped
+ * in the shell for `formFactor`. A package without screens gets one, its first
+ * template. The Engine keeps the ORIGINAL package (its signature, its grants);
+ * only the painter sees this one.
+ */
+export declare function runnerPackage(pkg: Pkg, formFactor: FormFactor): Pkg;
+/** What the runner paints instead of the app when its bundle cannot load. */
+export declare function runnerFailure(kind: RunnerFailure): SurfaceComponent[];
+/** The failed-action toast (a refused call, a refused link): surface `toast`; a broker reason code reads as `copy.refusals`. */
+export declare function runnerToast(message: string): SurfaceComponent[];
+export {};