ptbk 0.119.0-72 → 0.119.0-75

package/dist/app/api/engine-api.d.ts

@@ -0,0 +1,117 @@
+import type { OnboardingSession } from '../../onboarding/session.js';
+import type { Agenda } from '../../engine/agenda.js';
+import { type ContractProblem } from '../../vendor/app-platform.js';
+import type { AppSecurityFacts } from '../connection.js';
+import type { AccessStore, Actor } from '../web/access.js';
+/**
+ * Capabilities this engine advertises in `GET /engine` (every route of each works). The core API needs none.
+ *
+ * @private App engine API
+ */
+export declare const ADVERTISED_CAPABILITIES: readonly {
+    readonly id: string;
+    readonly version: number;
+}[];
+/**
+ * What the engine API needs from the running engine.
+ *
+ * @private App engine API
+ */
+export type EngineApiDeps = {
+    readonly agenda?: Agenda;
+    readonly onboarding?: OnboardingSession;
+    readonly projectRoot: string;
+    /** The App data directory, where the API keeps its state beside the Books. */
+    readonly stateDirectory: string;
+    readonly engineId: () => string | undefined;
+    readonly hostname: () => string | undefined;
+    readonly dashboardUrl: () => string | undefined;
+    readonly security: () => AppSecurityFacts | undefined;
+    /** `GET /security` → `ui`: the served engine UI (a verified bundle, or the engine's own page) and its last check. */
+    readonly ui: () => Record<string, unknown>;
+    readonly log?: (text: string, level: 'info' | 'warning' | 'error') => void;
+};
+/**
+ * A contract ID for an engine name: the name itself when it fits the opaque ID pattern, else a readable prefix and a
+ * digest.
+ *
+ * @private App engine API
+ */
+export declare function opaqueIdOf(name: string): string;
+/**
+ * The Reborn engine API (`@ptbk/engine-api` v1) over the project's own domain operations: agents are the project's
+ * Books (with their origin), chats are its `CHAT` threads with real authors, and members, passkeys and sessions are
+ * the gateway's. Every request is validated with the route's strict schemas, authorized by permission (denials change
+ * nothing), held to step-up where the route asks for it, and answered with exactly the route's response schema.
+ *
+ * @private App engine API
+ */
+export declare class EngineApi {
+    private readonly deps;
+    private readonly startedAt;
+    private readonly agentNames;
+    private stateOpening?;
+    constructor(deps: EngineApiDeps);
+    /** Project operations exist only after the regular service takes ownership. */
+    private get agenda();
+    /** The capabilities available at this stage of the engine's lifecycle. */
+    private get capabilities();
+    /** Serves one `/api/v1/...` request of a signed-in member. */
+    handle(request: Request, actor: Actor, access: AccessStore): Promise<Response>;
+    /** The API state, opened on first use (a failed open is retried by the next request). */
+    private state;
+    /** Validates, authorizes and runs one operation. */
+    private dispatch;
+    /** A domain error as a contract problem (never with internal details). */
+    private problemOf;
+    /** The project's agents (content, core and the engine's own) as API agents. */
+    private agents;
+    /** One API agent from its engine view and Book. */
+    private agentOf;
+    /** One agent by ID. */
+    private agent;
+    /** An agent's activity as the contract's status. */
+    private agentStatus;
+    /** A chat participant from an engine reference. */
+    private participant;
+    /** A chat's members, the User first. */
+    private members;
+    /** When a chat's Book was created and last changed. */
+    private chatTimes;
+    /** A chat summary as the contract's `Chat` (questions from the detail when given, else the unseen pings). */
+    private chat;
+    /** A participant reference without its display name. */
+    private authorRef;
+    /** One chat by name with its detail. */
+    private chatByName;
+    /** One stored message as the contract's `Message`. */
+    private message;
+    /** A thread's entries, oldest first: every member joins before writing, and a reply in progress streams last. */
+    private entries;
+    /** The 1-based position of a message ID of a chat, if it is one. */
+    private position;
+    /** A reply as deterministic deltas, then exactly one `completed` or `failed`. */
+    private replyStream;
+    /** What the event stream compares between changes. */
+    private eventDigest;
+    /** Live changes as `agent.status`, `agent.changed` and `chat.changed` events until the client leaves. */
+    private eventStream;
+    /** The members list entry of the contract. */
+    private member;
+    /** A passkey as the contract lists it. */
+    private passkey;
+    /** A session as the contract lists it. */
+    private session;
+    /** The engine settings the API exposes. */
+    private settings;
+    /** The security overview: versions, update state, certificate, relays, hostnames, the last heartbeat. */
+    private security;
+    /** The handlers by route ID. */
+    private readonly handlers;
+}
+/**
+ * Problems are plain objects; this keeps the type importable for handlers elsewhere.
+ *
+ * @private App engine API
+ */
+export type EngineApiProblem = ContractProblem;