@intentic/extension-api 1.337.0 → 1.339.0

package/src/runtime.ts

@@ -5,6 +5,7 @@ import { createBackoff, sleep, within } from "@intentic/base/async";
 import { errorMessage, undefinedIfMissing } from "@intentic/base/errors";
 import { FetchJsonError, fetchJson } from "@intentic/base/fetch-json";
 import { queueOnFile, writeFileAtomic } from "@intentic/base/fs";
+import { parseJsonWith } from "@intentic/base/json";
 import { sandboxRouteAllowed } from "@intentic/extension-manifest/permissions";
 import type * as SandboxContract from "@intentic/sandbox-contract";
 import { readDocument } from "@intentic/sandbox-contract/documents";
@@ -25,6 +26,7 @@ import type * as OrpcClient from "@orpc/client";
 import type * as OpenApiFetch from "@orpc/openapi-client/fetch";
 import type { Disposable } from "./disposable.js";
 import type {
+    ApprovedActionHandler,
     BackendRouteHandler,
     ExtensionHealth,
     ExtensionProcessApi,
@@ -43,6 +45,9 @@ import { extensionApiVersion } from "./version.js";
 // The backend half's types, from here as well as from the package root: the root also carries the browser half, whose
 // types name Vue's, which a gateway's program has no business loading.
 export type {
+    ApprovedAction,
+    ApprovedActionHandler,
+    ApprovedActionOutcome,
     BackendRouteHandler,
     ExtensionHealth,
     ExtensionHealthState,
@@ -198,18 +203,11 @@ const splitLines = (buffer: string) => {
 // The values a frame carries for its listeners, or undefined for a line this version cannot read (not JSON, or a kind a
 // newer daemon sends), which is skipped rather than fatal.
 const frameOf = (line: string): { readonly kind: ExtensionEventKind; readonly values: readonly string[] } | undefined => {
-    let raw: unknown;
-    try {
-        raw = JSON.parse(line);
-    } catch {
-        // allow(silent-catch): a line that is not JSON is a frame this version cannot read, skipped like an unknown kind
-        return undefined;
-    }
-    const parsed = ExtensionEventSchema.safeParse(raw);
-    if (!parsed.success) {
+    // A line that is not JSON is a frame this version cannot read, skipped like an unknown kind.
+    const event = parseJsonWith(line, ExtensionEventSchema);
+    if (event === undefined) {
         return undefined;
     }
-    const event = parsed.data;
     switch (event.kind) {
         case "heartbeat":
             return undefined;
@@ -412,12 +410,14 @@ export const createExtensionRuntime = (options: ExtensionRuntimeOptions): Extens
     };
 };
 
-// The backend api a `server` bundle is handed: the runtime plus the two slots only the host serves, its route namespace
-// and its tools. A second `mount` or `serve` replaces the first, per the api's contract.
+// The backend api a `server` bundle is handed: the runtime plus the slots only the host serves, its route namespace, its
+// tools and the approved actions it carries out. A second `mount`, `serve` or `perform` replaces the first, per the
+// api's contract.
 export interface ServerApiSlots {
     readonly api: ExtensionServerApi;
     readonly handler: () => BackendRouteHandler | undefined;
     readonly tools: () => ToolSource | undefined;
+    readonly performer: () => ApprovedActionHandler | undefined;
     close(): void;
 }
 
@@ -425,6 +425,7 @@ export const createServerApi = (options: ExtensionRuntimeOptions): ServerApiSlot
     const runtime = createExtensionRuntime(options);
     let mounted: BackendRouteHandler | undefined;
     let tools: ToolSource | undefined;
+    let performer: ApprovedActionHandler | undefined;
     return {
         api: {
             ...runtime.api,
@@ -438,9 +439,15 @@ export const createServerApi = (options: ExtensionRuntimeOptions): ServerApiSlot
                     tools = source;
                 },
             },
+            approvals: {
+                perform: (handler) => {
+                    performer = handler;
+                },
+            },
         },
         handler: () => mounted,
         tools: () => tools,
+        performer: () => performer,
         close: runtime.close,
     };
 };

package/src/server.ts

@@ -57,6 +57,39 @@ export interface ToolDefinition {
 // the host answers 404.
 export type BackendRouteHandler = (request: Request) => Promise<Response | undefined>;
 
+// An action in the approvals queue that names this extension as its `performer`, handed over by the daemon only after
+// it found a person's yes on record matching the item as it stands, and spent that yes. The workspace file is never
+// what decides: an item marked approved without a recorded yes, or changed since, never reaches the backend.
+export interface ApprovedAction {
+    // The item's id in the approvals queue.
+    readonly id: string;
+    // `performer.digest` as the yes pinned it: the SHA-256 the extension wrote when it held the act. The extension
+    // recomputes it over what it is about to do and refuses on any difference.
+    readonly digest: string;
+    // The item's headline and details, exactly as they stood when the person said yes.
+    readonly summary: string;
+    readonly details: string;
+    // Who said yes (their sign-in) and when, as the daemon recorded it. No approver when the sandbox runs without
+    // sign-in. A yes given again (a retry) has a later `approvedAt`, so the pair names one yes.
+    readonly approver?: string | undefined;
+    readonly approvedAt: number;
+    // The sandbox's action rules as the daemon reads them now, organisation pins applied: a rule set to deny after the
+    // yes still refuses.
+    readonly actionRules: Readonly<Record<string, string>>;
+}
+
+// What carrying out an approved action came to, in the three states the queue keeps apart.
+export type ApprovedActionOutcome =
+    // It happened. `result` is the row's one line: a registry number, a task id.
+    | { readonly outcome: "done"; readonly result: string }
+    // It did not happen and nothing reached the outside world, so a new yes may safely run it again.
+    | { readonly outcome: "refused"; readonly error: string }
+    // It may have happened: the request went out and its answer failed or was lost part-way. The queue never repeats
+    // it by itself; the person checks the outside system first.
+    | { readonly outcome: "uncertain"; readonly error: string };
+
+export type ApprovedActionHandler = (action: ApprovedAction, context: { readonly signal: AbortSignal }) => Promise<ApprovedActionOutcome>;
+
 // An extension's own setting values, keyed as its manifest's `contributes.settings` declares them.
 export type ExtensionSettingValues = Readonly<Record<string, string | number | boolean>>;
 
@@ -157,6 +190,13 @@ export interface ExtensionServerApi {
     readonly tools: {
         serve(tools: (card: ToolCard | undefined) => readonly ToolDefinition[] | Promise<readonly ToolDefinition[]>): void;
     };
+    // The approved actions this extension carries out itself, in place of an agent turn: an approvals-queue item whose
+    // `performer` names this extension reaches `perform` from the daemon's approvals executor alone, through a door of
+    // the backend host that no /x route, panel or agent token reaches, after the daemon has matched and spent the yes.
+    // The credentials stay in the backend, read from the daemon. A second perform replaces the first.
+    readonly approvals: {
+        perform(handler: ApprovedActionHandler): void;
+    };
     // Authenticated transport to the daemon's own routes; every call is checked against the manifest's
     // `permissions.daemon` allowlist.
     readonly daemon: {
@@ -175,9 +215,10 @@ export interface ExtensionServerContext {
 }
 
 // What a declared process (`contributes.processes`) gets, from `connectExtensionProcess` in
-// `@intentic/extension-api/runtime`: the backend's api without the two halves only the backend host can serve. A
-// process answers on its own port, so it mounts no routes and serves tools there (`contributes.tools.process`).
-export type ExtensionProcessApi = Omit<ExtensionServerApi, "routes" | "tools">;
+// `@intentic/extension-api/runtime`: the backend's api without the halves only the backend host can serve. A process
+// answers on its own port, so it mounts no routes, serves tools there (`contributes.tools.process`) and carries out no
+// approved action.
+export type ExtensionProcessApi = Omit<ExtensionServerApi, "routes" | "tools" | "approvals">;
 
 // Shape of the manifest `server` bundle's default (or named) export; `activateServer` runs once per activation, which
 // is once per backend-host start unless the extension returns a `deactivate`, after which a change to it alone

package/src/stream.ts

@@ -1,4 +1,4 @@
-import { sseEvents, sseJson } from "@intentic/sandbox-contract";
+import { sseEvents, sseJson } from "@intentic/sandbox-contract/protocol/sse";
 
 // Reads a daemon SSE/ndjson stream: reframes blank-line-separated `data: <JSON>` frames and parses each, through the
 // contract's one SSE reader, which ends a stream silent past its heartbeat window rather than hanging on it.