@zackbart/connecta 0.25.0 → 0.26.0

package/dist/operator-ui/model.d.ts

@@ -6,13 +6,16 @@ import type { CatalogAccessObservation, CatalogDriftReport } from "../types.js";
  * the rule is a second place for it to be wrong.
  *
  * - `runs_in_programs` — explicitly read-only, so `execute_code` may call it.
- * - `needs_approval` — everything else, which crosses `call_destructive_tool`.
+ * - `exempt` — not read-only, but the deployment's `execute.approval` lets a
+ *   program call it without pausing (#566). Still approval-required
+ *   everywhere else.
+ * - `needs_approval` — everything else: a program pauses for
+ *   `resume_execution`, and a direct call crosses `call_destructive_tool`.
  *
- * Planned resumable writes add a third value for a config `approval: "never"`
- * exemption; the badge renders from a table keyed by this union so that value
- * is one entry, not a new branch.
+ * The badge renders from a table keyed by this union, so each value is one
+ * entry, not a branch.
  */
-export type UiToolSafety = "runs_in_programs" | "needs_approval";
+export type UiToolSafety = "runs_in_programs" | "exempt" | "needs_approval";
 export interface UiTool {
     name: string;
     address: string;
@@ -122,6 +125,60 @@ export interface UiData {
      * it with a 404, so the page never enumerates a pool its reader cannot open.
      */
     pools?: string[];
+    /** True when artifact pages are mounted and this identity may open them. */
+    artifactsEnabled?: boolean;
+}
+/**
+ * One row of the artifact library. Every field is a fact the store keeps or
+ * an enum; nothing here is a message, a log line, or a downstream's words.
+ */
+export interface UiArtifactRow {
+    id: string;
+    title: string;
+    kind: "html" | "markdown";
+    viewVersion: number;
+    updatedAt: string;
+    updatedBy: {
+        label: string;
+    };
+    archived: boolean;
+    freshness?: UiArtifactFreshness;
+}
+interface UiArtifactFreshness {
+    state: "unconfigured" | "current" | "stale";
+    schedule?: "manual" | "daily" | "weekly";
+    document?: string;
+    dueAt?: string;
+    last?: {
+        at: string;
+        status: "succeeded" | "unchanged" | "failed" | "superseded";
+    };
+    running?: boolean;
+}
+/** The viewer's payload: the page's facts and the one document its frame loads. */
+export interface UiArtifactView {
+    id: string;
+    title: string;
+    kind: "html" | "markdown";
+    archived: boolean;
+    snapshot: boolean;
+    latestViewVersion: number;
+    view: {
+        version: number;
+        at: string;
+        by: {
+            label: string;
+        };
+    };
+    documents: {
+        name: string;
+        version: number;
+        updatedAt: string;
+    }[];
+    url: string;
+    snapshotUrl: string;
+    document: string;
+    freshness?: UiArtifactFreshness;
 }
 export interface FilteredUiConnector {
     connector: UiConnector;

package/dist/operator-ui/view.js

@@ -1,21 +1,85 @@
+/** Pages the nav lists. A single artifact is reached from the library, not the nav. */
 export const OPERATOR_PAGES = [
     "connections",
     "activity",
+    "artifacts",
 ];
 export const PAGE_META = {
     connections: { path: "/", label: "Connections" },
     activity: { path: "/activity", label: "Activity" },
+    artifacts: { path: "/artifacts", label: "Artifacts" },
+    artifact: { path: "/artifacts", label: "Artifact" },
 };
 export function pageForPath(path) {
+    if (path.startsWith("/artifacts/"))
+        return "artifact";
     const match = OPERATOR_PAGES.find((page) => PAGE_META[page].path === path);
     return match ?? "connections";
 }
+/** Artifact pages load their own data and never ask `/ui/data` whether to open. */
+export function isArtifactPage(page) {
+    return page === "artifacts" || page === "artifact";
+}
+/**
+ * Where a viewer's frame gets its page: `/artifacts/<id>` or a snapshot,
+ * `/artifacts/<id>/v/<version>?d=<name>:<version>…`, mapped to its API call.
+ */
+export function artifactViewRequest(pathname, search) {
+    const match = /^\/artifacts\/([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)(?:\/v\/(\d{1,9}))?$/.exec(pathname);
+    if (!match?.[1])
+        return undefined;
+    const params = new URLSearchParams();
+    if (match[2]) {
+        params.set("v", match[2]);
+        for (const pin of new URLSearchParams(search).getAll("d"))
+            params.append("d", pin);
+    }
+    const query = params.toString();
+    return `/artifacts/_api/view/${match[1]}${query ? `?${query}` : ""}`;
+}
 export function info(message) {
     return { message, tone: "info" };
 }
 export function failure(message, fix) {
     return fix ? { message, tone: "error", fix } : { message, tone: "error" };
 }
+const REFUSED_COPY = {
+    oauth_disconnect: "OAuth disconnect failed. If the downstream refused it, the deployment's log has its reply.",
+    oauth_reconnect: "OAuth authorization could not restart. If the downstream refused it, the deployment's log has its reply.",
+    credential_test: "The credential test could not run.",
+};
+/** The route's answer to a finished OAuth action. Its state picks the sentence. */
+export function oauthDoneNotice(action, answer) {
+    if (action === "oauth_disconnect") {
+        return info("OAuth disconnected. Restart authorization when you are ready to reconnect.");
+    }
+    return info(answer?.state === "ok"
+        ? "OAuth reconnected."
+        : "Authorization restarted. Open the authorization link to reconnect.");
+}
+/** A credential Test's result. `ok` is the only part of the answer it reads. */
+export function credentialTestNotice(connectorId, answer) {
+    return answer?.ok === true
+        ? info("Credential is valid.")
+        : failure("Credential test failed: the downstream rejected the stored credential, or the test could not reach it. The deployment's log has the downstream's reply.", { kind: "credential_test_failed", connectorId });
+}
+/**
+ * A route that refused one of these actions. A credential Test that found
+ * nothing usable to test names the problem, which picks the same copy and fix
+ * prompt the Connections page uses for it; every other refusal gets the
+ * action's one sentence. `problem` is whatever the response carried, so it is
+ * checked, not trusted.
+ */
+export function refusedNotice(action, connectorId, problem) {
+    if (action === "credential_test" &&
+        (problem === "credential_required" || problem === "credential_mismatch")) {
+        return failure(PROBLEM_COPY[problem], { kind: problem, connectorId });
+    }
+    return failure(REFUSED_COPY[action], {
+        kind: action === "credential_test" ? "credential_test_failed" : "oauth_action_failed",
+        connectorId,
+    });
+}
 export function initialState(page) {
     return {
         page,
@@ -46,6 +110,13 @@ function identityScopedState() {
         activityEvents: [],
         activityCursor: null,
         activitySearch: "",
+        artifactPhase: "idle",
+        artifactNotice: null,
+        artifactRows: [],
+        artifactCursor: null,
+        artifactQuery: "",
+        artifactArchived: false,
+        artifactView: null,
     };
 }
 /**
@@ -151,8 +222,8 @@ export function connectorSummaryParts(summary) {
     ];
 }
 /**
- * The badge for each call path, keyed by the server's classification so the
- * planned third state is a row here rather than a new branch in a component.
+ * The badge for each call path, keyed by the server's classification so each
+ * state is a row here rather than a branch in a component.
  */
 export const TOOL_SAFETY_BADGE = {
     runs_in_programs: {
@@ -160,10 +231,15 @@ export const TOOL_SAFETY_BADGE = {
         tone: "ok",
         title: "Explicitly read-only: execute_code programs may call it without asking.",
     },
+    exempt: {
+        label: "exempt from approval",
+        tone: "neutral",
+        title: "Not read-only, but this deployment's config lets programs call it without pausing. Each call still counts against the write budget and appears in activity; call_tool still refuses it.",
+    },
     needs_approval: {
-        label: "needs approval",
+        label: "asks for approval",
         tone: "warn",
-        title: "Not explicitly read-only: calls cross call_destructive_tool, where the host asks first.",
+        title: "Not explicitly read-only: a program pauses for resume_execution, and a direct call crosses call_destructive_tool — either way the host asks first.",
     },
 };
 /**
@@ -320,13 +396,26 @@ export function activitySummary(events) {
     const tools = new Set(events.map((event) => event.address)).size;
     return `${events.length} loaded call${events.length === 1 ? "" : "s"} · ${tools} tool${tools === 1 ? "" : "s"} · no arguments or results stored`;
 }
-const ACTIVITY_OUTCOMES = ["success", "error", "timeout", "cancelled"];
+// A pause and an approval are neither success nor failure: each gets its own
+// class, and the stylesheet paints neither as an error.
+const ACTIVITY_OUTCOMES = [
+    "success",
+    "error",
+    "timeout",
+    "cancelled",
+    "paused",
+    "approved",
+];
 export function activityOutcomeClass(outcome) {
     return ACTIVITY_OUTCOMES.includes(outcome) ? outcome : "error";
 }
 /** The one-line detail under an address: source, retries, and friction. */
 export function activityDetail(event) {
     const parts = [event.source];
+    if (event.approval === "tool")
+        parts.push("approved for the rest of the run");
+    if (event.approval === "call")
+        parts.push("approved for this call");
     if (event.attempts > 1)
         parts.push(`${event.attempts} attempts`);
     if (event.friction)

package/dist/program-source.js

@@ -3,6 +3,8 @@
 // QuickJS normalizer runs it too for callers that drive that executor directly.
 /** A whole-program markdown fence, as QuickJS's normalizer recognizes one. */
 const FENCE = /^```[\w-]*\s*\n([\s\S]*?)\n?```$/;
+/** Intake accepts one JavaScript fence, optionally surrounded by prose. */
+const PROGRAM_FENCE = /^```(?:js|javascript)?[ \t]*\r?\n([\s\S]*?)\r?\n```[ \t]*$/gm;
 /** Leading whitespace and comments, which may precede the arrow expression. */
 const LEADING_TRIVIA = /^(?:\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\/)+/;
 /** One character of an identifier, keyword, or number; `\\` for escapes. */
@@ -44,6 +46,120 @@ export function withoutProgramTerminator(code) {
     const stripped = stripTerminators(source);
     return stripped === source ? code : stripped;
 }
+/**
+ * Recover wrappers that models put around a single program. This runs in the
+ * host, so QuickJS and Dynamic Workers receive the same source. It does not
+ * turn arbitrary statements into a program: an arrow remains the contract.
+ */
+export function normalizeProgramSource(code) {
+    let source = code.trim();
+    const head = source.replace(LEADING_TRIVIA, "");
+    // A program may itself contain fenced Markdown in a comment or string. Once
+    // the source starts as a program, a fence inside it is data, never a wrapper.
+    if (!/^(?:async\b|\(|export\s+default\s+async\b)/.test(head)) {
+        const fences = [...source.matchAll(PROGRAM_FENCE)];
+        if (fences.length === 1) {
+            const fence = fences[0];
+            const outside = source.slice(0, fence.index) + source.slice(fence.index + fence[0].length);
+            const body = fence[1].trim();
+            const fencedHead = body.replace(LEADING_TRIVIA, "");
+            if (!outside.includes("```") && /^(?:async\b|\(|export\s+default\s+async\b)/.test(fencedHead)) {
+                source = body;
+            }
+        }
+    }
+    source = source.replace(/^export\s+default\s+(?=async\s*(?:\(|[A-Za-z_$]))/, "");
+    // The declaration must be the whole source. A scanner finds its own closing
+    // brace rather than mistaking a brace in a string or a second statement for
+    // the end of the function.
+    const named = /^async\s+function\s+([A-Za-z_$][\w$]*)\s*\(([^()]*)\)\s*\{/.exec(source);
+    if (named) {
+        const end = functionBodyEnd(source, named[0].length - 1);
+        if (end !== undefined && /^(?:\s|;|\/\/[^\n]*|\/\*[\s\S]*?\*\/)*$/.test(source.slice(end + 1))) {
+            // Invoke a named function expression inside the arrow. Its own name and
+            // `arguments` binding then work exactly as in the original declaration.
+            source = `async (...args) => (async function ${named[1]}(${named[2]}) {${source.slice(named[0].length, end)}})(...args)${source.slice(end + 1)}`;
+        }
+    }
+    return withoutProgramTerminator(source);
+}
+/** Find the matching closing brace of a named function's body. */
+function functionBodyEnd(source, open) {
+    let depth = 0;
+    let previous = "";
+    for (let i = open; i < source.length; i++) {
+        const c = source[i];
+        if (/\s/.test(c))
+            continue;
+        if (c === "/" && source[i + 1] === "/") {
+            const end = source.indexOf("\n", i + 2);
+            i = end === -1 ? source.length : end;
+            continue;
+        }
+        if (c === "/" && source[i + 1] === "*") {
+            const end = source.indexOf("*/", i + 2);
+            if (end === -1)
+                return undefined;
+            i = end + 1;
+            continue;
+        }
+        if (c === "'" || c === '"' || c === "`") {
+            let end = i + 1;
+            for (; end < source.length && source[end] !== c; end++) {
+                if (source[end] === "\\")
+                    end++;
+                else if (source[end] === "\n" && c !== "`")
+                    return undefined;
+            }
+            if (end >= source.length)
+                return undefined;
+            i = end;
+            previous = "0";
+            continue;
+        }
+        if (c === "/" && startsRegex(previous)) {
+            let end = i + 1;
+            let inClass = false;
+            for (; end < source.length; end++) {
+                const r = source[end];
+                if (r === "\n")
+                    return undefined;
+                if (r === "\\")
+                    end++;
+                else if (r === "[")
+                    inClass = true;
+                else if (r === "]")
+                    inClass = false;
+                else if (r === "/" && !inClass)
+                    break;
+            }
+            if (end >= source.length)
+                return undefined;
+            i = end;
+            previous = "0";
+            continue;
+        }
+        if (WORD.test(c)) {
+            let end = i + 1;
+            while (end < source.length && WORD.test(source[end]))
+                end++;
+            previous = source.slice(i, end);
+            i = end - 1;
+            continue;
+        }
+        if (c === "{")
+            depth++;
+        else if (c === "}") {
+            depth--;
+            if (depth === 0)
+                return i;
+            if (depth < 0)
+                return undefined;
+        }
+        previous = c;
+    }
+    return undefined;
+}
 function stripTerminators(source) {
     const head = source.replace(LEADING_TRIVIA, "");
     if (!/^async\b/.test(head) && !head.startsWith("("))

package/dist/registry.d.ts

@@ -3,6 +3,7 @@ import type { CatalogDriftReport, Connector, ConnectorContext, ConnectorStatus,
 import { type DeferredWork } from "./connector-scope.js";
 import { type CatalogDriftActivityContext } from "./activity.js";
 import { type CallAdmissionPermit, type ConnectorCallAdmissionSnapshot } from "./call-admission.js";
+import { type ConnectorCaller } from "./connector-caller.js";
 /**
  * Split `"<connectorId>.<toolName>"` on the first dot. Connector ids contain
  * no dots, so a downstream tool name may. Exported because an address that
@@ -129,8 +130,11 @@ export type ToolAccess = ReadonlyMap<string, ReadonlySet<string>>;
 export interface RegistryScope {
     connectorIds: "all" | readonly string[];
     toolAccess?: ToolAccess;
+    guardedToolAccess?: ToolAccess;
     subjectKey?: string;
     principalKey?: string;
+    /** The admitted caller, readable only by built-in connectors; see connector-caller.ts. */
+    caller?: ConnectorCaller;
 }
 /**
  * Holds the connector set, resolves addresses, and caches per-connector tool
@@ -147,7 +151,7 @@ export declare class Registry implements RegistryView {
     private readonly catalogGenerations;
     /** Serialize persisted catalog set/delete operations within this isolate. */
     private readonly catalogMutations;
-    /** Same-request cold loads share one promise without retaining the request.
+    /** Same-request cold loads share one read without retaining the request.
      * See documentation/architecture.md#the-two-lifetimes. */
     private readonly requestCatalogLoads;
     /** One live refresh per connector across agent and operator requests. */
@@ -283,11 +287,37 @@ export declare class Registry implements RegistryView {
     private enqueueCatalogMutation;
     private refreshToolsWithContext;
     /**
-     * Publish one shared refresh promise before starting its connector work.
-     * The first caller owns the scope and deadline; every later caller joins the
-     * result without gaining access to that context.
+     * Whether a refresh may still enter the shared cache layers: its generation
+     * is current, and the flight it runs in has been neither abandoned nor
+     * outlived its bound. Asked at each publication point, since listing and
+     * snapshotting both yield, and a late result must never overwrite the one a
+     * fresh attempt published in the meantime.
+     */
+    private mayPublish;
+    /**
+     * Publish one shared refresh before starting its connector work. The first
+     * caller owns the scope and signal, and the flight lives `boundMs` from now
+     * at most; every later caller joins the result without gaining access to
+     * that context. A flight found past its bound is abandoned here, and this
+     * caller starts the fresh attempt.
      */
     private startCatalogRefresh;
+    /**
+     * Give up on a flight that outlived its bound. Later readers start a fresh
+     * attempt, its joiners are told to, and nothing its owner lists from now on
+     * reaches a cache. The owner's work is left alone: it belongs to another
+     * request, which nothing here may reach into, and it can no longer publish.
+     */
+    private abandonCatalogRefresh;
+    /**
+     * Wait on another caller's flight, no longer than its bound. Succeeds with
+     * its tools, or with `undefined` when it will not answer for this caller —
+     * past its bound, when this waiter abandons it, or failed for its owner
+     * alone — so the caller makes a fresh attempt. The timer is this waiter's
+     * own: on workerd it is what keeps a request that waits on another alive,
+     * and bounded.
+     */
+    private joinCatalogRefresh;
     /** Force a live listTools refresh and replace both catalog cache layers. */
     private refreshTools;
     private observeCatalogAccess;
@@ -303,9 +333,15 @@ export declare class Registry implements RegistryView {
      * WeakMap neither roots the request scope nor lets its connector context
      * escape into another request; settled entries are also removed eagerly.
      *
+     * The read owns its signal, and each caller waits under its own: one that
+     * is cancelled while others wait leaves with its own failure, and the read
+     * is cancelled only when every caller has gone (src/runtime/shared-read.ts).
+     *
      * The deployment-wide flight below this layer coalesces the actual live
-     * refresh across requests. Its first caller's context and deadline govern;
-     * later callers join only its result, never its request scope.
+     * refresh across requests. Its owner's context governs the listing, and its
+     * owner's deadline bounds it; later callers join only its result, never its
+     * request scope, and a failure that was the owner's alone sends them to a
+     * fresh attempt rather than to them.
      */
     getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, readOptions?: CatalogReadOptions): Promise<ToolDef[]>;
     credentialDriftFor(id: string): Promise<string | undefined>;