@zackbart/connecta 0.37.1 → 0.39.0

package/dist/config.d.ts

@@ -18,8 +18,10 @@ declare const discovery: {
     /**
      * Deadline (ms) for each downstream probe/catalog call fanned out by
      * `search_tools` and by `connecta.search`/`connecta.describe` inside
-     * `execute_code`. Defaults to 30_000. A timed-out connector degrades
-     * independently; this does not apply to tool calls. Catalog walks receive the
+     * `execute_code`. Defaults to 30_000. An unscoped search caps each probe at
+     * 5_000 and its whole fan-out at 9_000, and skips a connector whose
+     * discovery recently timed out for up to 60 seconds. A timed-out connector
+     * degrades independently; this does not apply to tool calls. Catalog walks receive the
      * same cancellation signal, which aborts an in-flight page where supported and
      * prevents another from starting.
      */
@@ -28,11 +30,12 @@ declare const discovery: {
 declare const calls: {
     /**
      * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
-     * `timeoutMs`. An explicit per-call value wins. Opt-in: unset by default, so
-     * existing long-running calls gain no surprise deadline.
+     * `timeoutMs`. An explicit per-call value wins. Unset by default, when those
+     * calls fall back to `execute.hostCallTimeoutMs`.
      *
-     * Each call makes one attempt. `execute_code` host calls are
-     * unaffected because they already carry their own bound.
+     * Each call makes one attempt. `connecta.call` inside `execute_code` uses
+     * it too, ahead of `execute.hostCallTimeoutMs`; `connecta.result`,
+     * `connecta.skill` and `connecta.read` do not.
      */
     defaultTimeoutMs: import("./config-schema.js").Field<number, number | undefined, true>;
     /**
@@ -60,9 +63,12 @@ declare const execute: {
     /** Host calls one program may make. Default 20. */
     maxHostCalls: import("./config-schema.js").Field<number, number, true>;
     /**
-     * Deadline for each host call a program makes, in milliseconds. Default
-     * 15_000. Raise it for providers whose legitimate calls run longer, such as
-     * analytics queries; `call_tool`'s own `timeoutMs` is unaffected.
+     * Deadline for a program's `connecta.result`, `connecta.skill` and
+     * `connecta.read`, in milliseconds. Default 15_000. Discovery uses
+     * `discovery.probeTimeoutMs`. `connecta.call` and the direct call tools use it only when
+     * `calls.defaultTimeoutMs` is unset, and an explicit per-call `timeoutMs`
+     * always wins. Raise it for providers whose legitimate calls run longer,
+     * such as analytics queries.
      */
     hostCallTimeoutMs: import("./config-schema.js").Field<number, number, true>;
     /**
@@ -78,6 +84,14 @@ declare const execute: {
      * budget every call already spends. Default 10.
      */
     maxWrites: import("./config-schema.js").Field<number, number, true>;
+    /**
+     * Serialized characters a program may return, shared with emitted text,
+     * before Connecta stashes the return and answers with a paging notice.
+     * Default 24_000 (~6k tokens). Raise it when agents need large results whole
+     * and the model's context can afford them: each paging round trip costs a
+     * model step. From 4_000 to 1_000_000.
+     */
+    maxResultChars: import("./config-schema.js").Field<number, number, true>;
 };
 declare const codeAdmission: {
     /** Simultaneous work admitted to this pool. */
@@ -179,8 +193,9 @@ declare const pool: {
     /**
      * Who may open `/mcp/<name>`: principal ids in the namespace of the one
      * interactive auth provider, `{ namespace, id }`, or `"agent:<name>"` for a
-     * declared agent. Required and non-empty; the pool serves exactly its
-     * `tools` to these members and the same 404 to everyone else.
+     * declared agent. All members must be people or all must be agents. Required
+     * and non-empty; the pool serves exactly its `tools` to these members and
+     * the same 404 to everyone else.
      */
     members: import("./config-schema.js").Field<readonly MemberRef[], readonly MemberRef[], false>;
     /**
@@ -188,8 +203,8 @@ declare const pool: {
      * connector whose `subject` is a mapping function. Humans always act as
      * themselves through that mapping, and a fixed `subject` address applies to
      * everyone. Without an owner, a mapping-subject Workspace connector is
-     * absent for this pool's agents, as a personal connector is; people in the
-     * pool still see it.
+     * absent for this pool's agents, as a personal connector is. People use a
+     * separate pool and always act as themselves.
      */
     owner: import("./config-schema.js").Field<string, string | undefined, true>;
     /**
@@ -206,7 +221,7 @@ declare const pool: {
      * `<connector>__<tool>` and annotated from its classification, for clients
      * that run their own tool search; calls take the same invocation path.
      */
-    surface: import("./config-schema.js").Field<"native" | "meta", "native" | "meta" | undefined, true>;
+    surface: import("./config-schema.js").Field<"meta" | "native", "meta" | "native" | undefined, true>;
     /**
      * `false` drops `execute_code` from a native pool and lists `read_result`
      * for paging instead. Only valid with `surface: "native"`: the meta surface
@@ -242,7 +257,7 @@ declare const connectaConfig: {
         readOnly?: boolean | undefined;
         owner?: string | undefined;
         description?: string | undefined;
-        surface?: "native" | "meta" | undefined;
+        surface?: "meta" | "native" | undefined;
         executeCode?: boolean | undefined;
         tools: readonly string[];
         members: readonly MemberRef[];
@@ -252,7 +267,7 @@ declare const connectaConfig: {
         readonly members: readonly MemberRef[];
         readonly owner: string | undefined;
         readonly description: string | undefined;
-        readonly surface: "native" | "meta" | undefined;
+        readonly surface: "meta" | "native" | undefined;
         readonly executeCode: boolean | undefined;
     }>> | undefined, true>;
     /** Exact connector id -> tool name -> verdict. Hidden tools cannot be discovered or called.
@@ -314,8 +329,10 @@ declare const connectaConfig: {
             /**
              * Deadline (ms) for each downstream probe/catalog call fanned out by
              * `search_tools` and by `connecta.search`/`connecta.describe` inside
-             * `execute_code`. Defaults to 30_000. A timed-out connector degrades
-             * independently; this does not apply to tool calls. Catalog walks receive the
+             * `execute_code`. Defaults to 30_000. An unscoped search caps each probe at
+             * 5_000 and its whole fan-out at 9_000, and skips a connector whose
+             * discovery recently timed out for up to 60 seconds. A timed-out connector
+             * degrades independently; this does not apply to tool calls. Catalog walks receive the
              * same cancellation signal, which aborts an in-flight page where supported and
              * prevents another from starting.
              */
@@ -333,11 +350,12 @@ declare const connectaConfig: {
         readonly shape: {
             /**
              * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
-             * `timeoutMs`. An explicit per-call value wins. Opt-in: unset by default, so
-             * existing long-running calls gain no surprise deadline.
+             * `timeoutMs`. An explicit per-call value wins. Unset by default, when those
+             * calls fall back to `execute.hostCallTimeoutMs`.
              *
-             * Each call makes one attempt. `execute_code` host calls are
-             * unaffected because they already carry their own bound.
+             * Each call makes one attempt. `connecta.call` inside `execute_code` uses
+             * it too, ahead of `execute.hostCallTimeoutMs`; `connecta.result`,
+             * `connecta.skill` and `connecta.read` do not.
              */
             defaultTimeoutMs: import("./config-schema.js").Field<number, number | undefined, true>;
             /**
@@ -371,6 +389,7 @@ declare const connectaConfig: {
         hostCallTimeoutMs?: number | undefined;
         watchdogMs?: number | undefined;
         maxWrites?: number | undefined;
+        maxResultChars?: number | undefined;
     }, {
         readonly maxEmittedBytes: number;
         readonly maxEmittedBlocks: number;
@@ -378,6 +397,7 @@ declare const connectaConfig: {
         readonly hostCallTimeoutMs: number;
         readonly watchdogMs: number;
         readonly maxWrites: number;
+        readonly maxResultChars: number;
     }, true> & {
         readonly shape: {
             /**
@@ -391,9 +411,12 @@ declare const connectaConfig: {
             /** Host calls one program may make. Default 20. */
             maxHostCalls: import("./config-schema.js").Field<number, number, true>;
             /**
-             * Deadline for each host call a program makes, in milliseconds. Default
-             * 15_000. Raise it for providers whose legitimate calls run longer, such as
-             * analytics queries; `call_tool`'s own `timeoutMs` is unaffected.
+             * Deadline for a program's `connecta.result`, `connecta.skill` and
+             * `connecta.read`, in milliseconds. Default 15_000. Discovery uses
+             * `discovery.probeTimeoutMs`. `connecta.call` and the direct call tools use it only when
+             * `calls.defaultTimeoutMs` is unset, and an explicit per-call `timeoutMs`
+             * always wins. Raise it for providers whose legitimate calls run longer,
+             * such as analytics queries.
              */
             hostCallTimeoutMs: import("./config-schema.js").Field<number, number, true>;
             /**
@@ -409,6 +432,14 @@ declare const connectaConfig: {
              * budget every call already spends. Default 10.
              */
             maxWrites: import("./config-schema.js").Field<number, number, true>;
+            /**
+             * Serialized characters a program may return, shared with emitted text,
+             * before Connecta stashes the return and answers with a paging notice.
+             * Default 24_000 (~6k tokens). Raise it when agents need large results whole
+             * and the model's context can afford them: each paging round trip costs a
+             * model step. From 4_000 to 1_000_000.
+             */
+            maxResultChars: import("./config-schema.js").Field<number, number, true>;
         };
     };
     /**
@@ -654,5 +685,6 @@ export declare function executeLimits(config: ResolvedConfig): {
     hostCallTimeoutMs: number;
     watchdogMs: number;
     maxWrites: number;
+    maxResultChars: number;
 };
 export {};

package/dist/config.js

@@ -69,8 +69,10 @@ const discovery = {
     /**
      * Deadline (ms) for each downstream probe/catalog call fanned out by
      * `search_tools` and by `connecta.search`/`connecta.describe` inside
-     * `execute_code`. Defaults to 30_000. A timed-out connector degrades
-     * independently; this does not apply to tool calls. Catalog walks receive the
+     * `execute_code`. Defaults to 30_000. An unscoped search caps each probe at
+     * 5_000 and its whole fan-out at 9_000, and skips a connector whose
+     * discovery recently timed out for up to 60 seconds. A timed-out connector
+     * degrades independently; this does not apply to tool calls. Catalog walks receive the
      * same cancellation signal, which aborts an in-flight page where supported and
      * prevents another from starting.
      */
@@ -79,11 +81,12 @@ const discovery = {
 const calls = {
     /**
      * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
-     * `timeoutMs`. An explicit per-call value wins. Opt-in: unset by default, so
-     * existing long-running calls gain no surprise deadline.
+     * `timeoutMs`. An explicit per-call value wins. Unset by default, when those
+     * calls fall back to `execute.hostCallTimeoutMs`.
      *
-     * Each call makes one attempt. `execute_code` host calls are
-     * unaffected because they already carry their own bound.
+     * Each call makes one attempt. `connecta.call` inside `execute_code` uses
+     * it too, ahead of `execute.hostCallTimeoutMs`; `connecta.result`,
+     * `connecta.skill` and `connecta.read` do not.
      */
     defaultTimeoutMs: whole({ min: 1 }),
     /**
@@ -111,9 +114,12 @@ const execute = {
     /** Host calls one program may make. Default 20. */
     maxHostCalls: whole({ min: 1, default: D.execute.maxHostCalls }),
     /**
-     * Deadline for each host call a program makes, in milliseconds. Default
-     * 15_000. Raise it for providers whose legitimate calls run longer, such as
-     * analytics queries; `call_tool`'s own `timeoutMs` is unaffected.
+     * Deadline for a program's `connecta.result`, `connecta.skill` and
+     * `connecta.read`, in milliseconds. Default 15_000. Discovery uses
+     * `discovery.probeTimeoutMs`. `connecta.call` and the direct call tools use it only when
+     * `calls.defaultTimeoutMs` is unset, and an explicit per-call `timeoutMs`
+     * always wins. Raise it for providers whose legitimate calls run longer,
+     * such as analytics queries.
      */
     hostCallTimeoutMs: whole({ min: 1, default: D.execute.hostCallTimeoutMs }),
     /**
@@ -129,6 +135,14 @@ const execute = {
      * budget every call already spends. Default 10.
      */
     maxWrites: whole({ min: 1, default: D.execute.maxWrites }),
+    /**
+     * Serialized characters a program may return, shared with emitted text,
+     * before Connecta stashes the return and answers with a paging notice.
+     * Default 24_000 (~6k tokens). Raise it when agents need large results whole
+     * and the model's context can afford them: each paging round trip costs a
+     * model step. From 4_000 to 1_000_000.
+     */
+    maxResultChars: whole({ min: 4_000, max: 1_000_000, default: D.execute.maxResultChars }),
 };
 function admissionPool(defaults) {
     return {
@@ -225,8 +239,9 @@ const pool = {
     /**
      * Who may open `/mcp/<name>`: principal ids in the namespace of the one
      * interactive auth provider, `{ namespace, id }`, or `"agent:<name>"` for a
-     * declared agent. Required and non-empty; the pool serves exactly its
-     * `tools` to these members and the same 404 to everyone else.
+     * declared agent. All members must be people or all must be agents. Required
+     * and non-empty; the pool serves exactly its `tools` to these members and
+     * the same 404 to everyone else.
      */
     members: required(opaque({ check: assertMemberList }), (path) => `${path} is required: list who may open this pool, as principal ids, { namespace, id }, or "agent:<name>".`),
     /**
@@ -234,8 +249,8 @@ const pool = {
      * connector whose `subject` is a mapping function. Humans always act as
      * themselves through that mapping, and a fixed `subject` address applies to
      * everyone. Without an owner, a mapping-subject Workspace connector is
-     * absent for this pool's agents, as a personal connector is; people in the
-     * pool still see it.
+     * absent for this pool's agents, as a personal connector is. People use a
+     * separate pool and always act as themselves.
      */
     owner: opaque({
         check: (value, path) => {
@@ -492,48 +507,6 @@ const connectaConfig = {
     readOnly: required(opaque({ check: assertFlag }), (path) => READ_ONLY_REQUIRED(path)),
 };
 const CONFIG = object(connectaConfig);
-/** Pause-only options #672 removed with `resume_execution`. */
-const RETIRED_PAUSE_OPTIONS = ["ConnectaConfig.execute.resumableWrites", "ConnectaConfig.execute.pausedRunTtlSeconds"];
-/** Access options pools replaced (#837, decisions/0006). */
-const isRetiredPoolGrant = (path) => /^ConnectaConfig\.pools\.[^.]+\.grant$/.test(path);
-/** Management resolvers maintainers and pool membership replaced (#837, decisions/0006). */
-const RETIRED_IDENTITY = [
-    ["credentialAdministration", "maintainers administer shared credentials and OAuth grants. List them in maintainers."],
-    [
-        "personalConnection",
-        "pool members connect and disconnect their own personal connectors in their pools, and maintainers their own. Add people to a pool's members.",
-    ],
-    [
-        "accessTokenManagement",
-        "maintainers issue, rotate, and revoke agent tokens from an interactive session. List them in maintainers.",
-    ],
-    ["activityAccess", "maintainers read activity; activity.readGate can still narrow it. List them in maintainers."],
-];
-/** `trust`, on the deployment or a pool, was replaced by `readOnly` (#820). */
-const isRetiredTrust = (path) => path === "ConnectaConfig.trust" || (path.startsWith("ConnectaConfig.pools.") && path.endsWith(".trust"));
-/**
- * `identity` was removed whole (#837), so the walk reports only the section.
- * Name each key it still holds, read by descriptor without running a getter
- * or echoing a value, so a retired resolver's message names its replacement.
- */
-function expandRetiredIdentity(config, paths) {
-    if (!paths.includes("ConnectaConfig.identity"))
-        return paths;
-    let keys = [];
-    try {
-        const descriptor = Reflect.getOwnPropertyDescriptor(config, "identity");
-        const value = descriptor && "value" in descriptor ? descriptor.value : undefined;
-        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-            keys = Reflect.ownKeys(value).filter((key) => typeof key === "string");
-        }
-    }
-    catch {
-        keys = [];
-    }
-    if (keys.length === 0)
-        return paths;
-    return paths.flatMap((path) => path === "ConnectaConfig.identity" ? keys.map((key) => `ConnectaConfig.identity.${key}`) : [path]);
-}
 function rejectUnknownOptions(paths) {
     if (paths.length === 0)
         return;
@@ -547,27 +520,6 @@ function rejectUnknownOptions(paths) {
             : "") +
         (paths.includes("ConnectaConfig.execute.approval")
             ? "\nexecute.approval was removed. The MCP client owns approval; set readOnly: true on the deployment or a pool to refuse writes."
-            : "") +
-        (paths.some((path) => RETIRED_PAUSE_OPTIONS.includes(path))
-            ? "\nPrograms no longer pause at writes, so there is nothing to configure: writable endpoints let programs and call_destructive_tool write; readOnly endpoints refuse every write (issue #672). Delete the option."
-            : "") +
-        (paths.includes("ConnectaConfig.identity.connectorAccess")
-            ? "\nidentity.connectorAccess was removed (#837): pools are the access model. List who may use plain /mcp in maintainers, and give each pool its tools and members. A guarded { tool, requireReadOnly: true } grant becomes a pool with readOnly: true."
-            : "") +
-        RETIRED_IDENTITY.filter(([key]) => paths.includes(`ConnectaConfig.identity.${key}`))
-            .map(([key, replacement]) => `\nidentity.${key} was removed (#837): ${replacement}`)
-            .join("") +
-        (paths.some((path) => path === "ConnectaConfig.identity" || path.startsWith("ConnectaConfig.identity."))
-            ? "\nThe identity section was removed (#837): maintainers and pool members decide access and management. Delete it."
-            : "") +
-        (paths.includes("ConnectaConfig.grant")
-            ? "\nThe top-level grant was removed (#837); list the people who may use plain /mcp in maintainers."
-            : "") +
-        (paths.some(isRetiredPoolGrant)
-            ? "\nPool grant was removed (#837); list who may open the pool in its members."
-            : "") +
-        (paths.some(isRetiredTrust)
-            ? '\ntrust was removed (#820); set readOnly, which every deployment now chooses explicitly. trust: "read-only" becomes readOnly: true, which now also refuses call_destructive_tool. trust: "trusted" becomes readOnly: false. A pool inherits the deployment readOnly unless it sets its own.'
             : ""));
 }
 /** Checks that span fields; each value is already individually valid. */
@@ -598,7 +550,7 @@ export function resolveConfig(config) {
  */
 export function readConfig(config) {
     const read = readPlain(config, "ConnectaConfig", CONFIG);
-    rejectUnknownOptions(expandRetiredIdentity(config, read.unknown));
+    rejectUnknownOptions(read.unknown);
     const input = read.value;
     const parsed = CONFIG.parse(input, "ConnectaConfig");
     assertCoherent(parsed);
@@ -648,5 +600,6 @@ export function executeLimits(config) {
         hostCallTimeoutMs: config.execute.hostCallTimeoutMs,
         watchdogMs: config.execute.watchdogMs,
         maxWrites: config.execute.maxWrites,
+        maxResultChars: config.execute.maxResultChars,
     };
 }

package/dist/connector-caller.d.ts

@@ -9,7 +9,7 @@ export interface ConnectorCaller {
      * with or without a subject, a Connecta-issued access token.
      */
     authenticated: boolean;
-    /** The pool the call arrived on, at `/mcp/<pool>` or `/agent/<pool>`. */
+    /** The admitted pool: routed at `/mcp` or selected at `/mcp/<pool>` or `/agent/<pool>`. */
     pool?: string;
     /**
      * That pool's configured `owner`, the Workspace address an agent acts as

package/dist/connector-health.js

@@ -0,0 +1,59 @@
+// Where one connector's bounded health facts are stored for a registry view:
+// the catalog cache's store and owner partition (principal, subject, caller
+// identity and pool, origin) and the admitted endpoint, with the connector's
+// described configuration and the package version, through the deployment's
+// keyed digest (a described endpoint keeps its path), beside the catalog
+// invalidation generation those facts must match (INV-4, INV-5). Shared by
+// discovery health and the operator page's status observations.
+import { Effect } from "effect";
+import { catalogOwnerPartition } from "./catalog-policy.js";
+import { canonicalJson } from "./canonical-json.js";
+import { secretDigest } from "./storage-digest.js";
+import { responseCacheKeys } from "./storage/keys.js";
+import { CONNECTA_VERSION } from "./version.js";
+// A connector's described configuration, serialized once per connector object.
+// A change `describe()` cannot see, such as a static header rotated in
+// deployment code, takes effect on redeploy and leaves an earlier record to
+// lapse within its TTL.
+const configs = new WeakMap();
+function describedConfig(connector) {
+    let config = configs.get(connector);
+    if (config === undefined) {
+        let described = null;
+        try {
+            described = connector.describe?.() ?? null;
+        }
+        catch {
+            described = null;
+        }
+        config = canonicalJson([CONNECTA_VERSION, connector.kind ?? null, connector.authScope ?? null, described]);
+        configs.set(connector, config);
+    }
+    return config;
+}
+// The endpoint a request was admitted at (plain `/mcp`, a pool, an agent
+// path). The same person and pool can reach one connector through several,
+// and each keeps its own records. The operator page binds none.
+const endpoints = new WeakMap();
+/** Bind the admitted endpoint to a request scope, before any discovery runs in it. */
+export function bindDiscoveryEndpoint(requestScope, endpoint) {
+    endpoints.set(requestScope, endpoint);
+}
+/** Where one connector's records sit in this view's owner partition. */
+export function healthAddress(registry, id, baseUrl, requestScope) {
+    return Effect.suspend(() => {
+        const connector = registry.getConnector(id);
+        if (!connector)
+            return Effect.succeed(undefined);
+        const ctx = registry.contextFor(id, baseUrl, requestScope);
+        const { storage, partition } = catalogOwnerPartition(ctx);
+        if (!storage)
+            return Effect.succeed(undefined);
+        return Effect.promise(async () => ({
+            storage,
+            digest: await secretDigest(ctx, JSON.stringify([partition, endpoints.get(requestScope) ?? null, describedConfig(connector)])),
+            generationKey: responseCacheKeys.generation(id),
+            logger: ctx.logger,
+        }));
+    }).pipe(Effect.catchCause(() => Effect.succeed(undefined)));
+}

package/dist/connector-status.js

@@ -0,0 +1,117 @@
+// The operator page's stored connector status (#1173 item 2.3).
+//
+// A live detail read records what it saw, one observation per connector and
+// viewer partition, beside discovery health in the connector-health family and
+// under the same owner partition and catalog generation (INV-4, INV-5). The
+// detail route can then answer at once from storage, labelled with its age,
+// and the browser asks for a live read separately. An observation holds only
+// a state, a problem code, a tool count and its time (INV-6); the tools stay
+// in the complete catalog cache (INV-8). It is never deferred work: a live
+// read writes it before its response, and nothing refreshes it afterwards.
+import { Effect } from "effect";
+import { healthAddress } from "./connector-health.js";
+import { failureRecord, logFailure } from "./operator-record.js";
+import { causeError } from "./runtime/run.js";
+import { Storage } from "./runtime/services.js";
+import { requestReads } from "./runtime/request-scope.js";
+import { storageGet, storageGetMany, storageSet } from "./runtime/storage.js";
+import { connectorHealthKeys } from "./storage/keys.js";
+/** How long the operator page shows a stored status before only a live read will do. */
+const STATUS_OBSERVATION_TTL_MS = 120_000;
+const STATUS_STATES = new Set([
+    "ok",
+    "per_caller",
+    "auth_required",
+    "credential_required",
+    "error",
+]);
+const STATUS_PROBLEMS = new Set([
+    "connector_unavailable",
+    "connector_timeout",
+    "oauth_required",
+    "credential_required",
+    "auth_required",
+    "caller_refused",
+    "credential_mismatch",
+    "catalog_failed",
+]);
+/**
+ * This viewer's current observation of one connector, and the slot a live
+ * read writes its own to when there is none. A record from another generation, past its TTL or
+ * of an unknown shape is absent. A storage failure is absent too.
+ */
+export function readStatusObservation(registry, id, baseUrl, requestScope) {
+    return Effect.gen(function* () {
+        const address = yield* healthAddress(registry, id, baseUrl, requestScope);
+        if (!address)
+            return {};
+        const key = connectorHealthKeys.status(id, address.digest);
+        const values = yield* storageGetMany([key, address.generationKey]).pipe(Effect.provideService(Storage, address.storage), Effect.catchCause((cause) => Effect.sync(() => {
+            logFailure(address.logger, "discovery health read failed", failureRecord({}, causeError(cause)));
+            return undefined;
+        })));
+        if (!values)
+            return {};
+        const slot = { storage: address.storage, key, logger: address.logger, generation: values[1] ?? null };
+        try {
+            const value = JSON.parse(values[0] ?? "null");
+            if (value?.v === 1 &&
+                value.generation === slot.generation &&
+                typeof value.state === "string" &&
+                STATUS_STATES.has(value.state) &&
+                (value.problem === undefined || STATUS_PROBLEMS.has(value.problem)) &&
+                Number.isSafeInteger(value.toolCount) &&
+                value.toolCount >= 0 &&
+                Number.isFinite(value.observedAt) &&
+                Date.now() - value.observedAt < STATUS_OBSERVATION_TTL_MS)
+                return {
+                    slot,
+                    observation: {
+                        state: value.state,
+                        ...(value.problem ? { problem: value.problem } : {}),
+                        toolCount: value.toolCount,
+                        observedAt: value.observedAt,
+                    },
+                };
+        }
+        catch {
+            /* An unreadable record is absent. */
+        }
+        return { slot };
+    });
+}
+/**
+ * Where a live read will record its observation, without reading the stored
+ * one. The generation is read through the request's read memo: a live read's
+ * catalog listing locates its cache entry by that same key, so the listing
+ * reuses this read instead of paying another round trip. A generation is never
+ * reused once replaced, so a memoized value can only lapse an observation
+ * early, never keep one past an invalidation that preceded this request.
+ */
+export function prepareStatusSlot(registry, id, baseUrl, requestScope) {
+    return Effect.gen(function* () {
+        const address = yield* healthAddress(registry, id, baseUrl, requestScope);
+        if (!address)
+            return undefined;
+        const generation = yield* requestReads(requestScope)
+            .read(address.storage, address.generationKey, storageGet(address.generationKey))
+            .pipe(Effect.provideService(Storage, address.storage), Effect.catchCause((cause) => Effect.sync(() => {
+            logFailure(address.logger, "discovery health read failed", failureRecord({}, causeError(cause)));
+            return undefined;
+        })));
+        if (generation === undefined)
+            return undefined;
+        return {
+            storage: address.storage,
+            key: connectorHealthKeys.status(id, address.digest),
+            logger: address.logger,
+            generation,
+        };
+    });
+}
+/** Record what a live read saw. A failed write is logged; the page already has its answer. */
+export function storeStatusObservation(slot, observation) {
+    return storageSet(slot.key, JSON.stringify({ v: 1, ...observation, generation: slot.generation }), {
+        expiresAtMs: Math.ceil(observation.observedAt + STATUS_OBSERVATION_TTL_MS),
+    }).pipe(Effect.provideService(Storage, slot.storage), Effect.catchCause((cause) => Effect.sync(() => logFailure(slot.logger, "discovery health write failed", failureRecord({}, causeError(cause))))));
+}

package/dist/connectors/api-connector.d.ts

@@ -204,8 +204,8 @@ export declare const API_OPTIONS: import("../config-schema.js").Field<unknown, u
         credential: import("../config-schema.js").Field<unknown, unknown, true> & {
             readonly shape: {
                 fields: import("../config-schema.js").Field<unknown[], readonly unknown[] | undefined, true>;
-                label: import("../config-schema.js").Field<unknown, unknown, true>;
                 description: import("../config-schema.js").Field<unknown, unknown, true>;
+                label: import("../config-schema.js").Field<unknown, unknown, true>;
                 placeholder: import("../config-schema.js").Field<unknown, unknown, true>;
             };
         };
@@ -228,9 +228,9 @@ export declare const API_OPTIONS: import("../config-schema.js").Field<unknown, u
         };
         tools: import("../config-schema.js").Field<unknown[], readonly unknown[] | undefined, true>;
         title: import("../config-schema.js").Field<unknown, unknown, true>;
+        description: import("../config-schema.js").Field<unknown, unknown, true>;
         authScope: import("../config-schema.js").Field<unknown, unknown, true>;
         maxResultBytes: import("../config-schema.js").Field<unknown, unknown, true>;
-        description: import("../config-schema.js").Field<unknown, unknown, true>;
         testCredential: import("../config-schema.js").Field<unknown, unknown, true>;
         testCredentials: import("../config-schema.js").Field<unknown, unknown, true>;
         validateArgs: import("../config-schema.js").Field<unknown, unknown, true>;
@@ -244,6 +244,11 @@ export declare const API_OPTIONS: import("../config-schema.js").Field<unknown, u
  */
 export interface ApiOAuthHooks {
     status(ctx: ConnectorContext): Promise<ConnectorStatus>;
+    /**
+     * `status` for a call about to enter a handler, which also renews a token
+     * within a minute of its stored expiry. A failed renewal rejects.
+     */
+    prepareCall(ctx: ConnectorContext): Promise<ConnectorStatus>;
     startAuth(ctx: ConnectorContext, opts?: {
         force?: boolean;
     }): Promise<ConnectorStatus>;

package/dist/connectors/api-connector.js

@@ -1,3 +1,5 @@
+import { declaresRouteDescriptions, routePhrases } from "../agent-routes.js";
+import { wrapViewCredentials } from "../runtime/call.js";
 import { storedAuthObservation, withStoredAuth } from "../auth/stored-observation.js";
 import { Effect, Exit } from "effect";
 import { registerConnectorVocabulary } from "../operation-vocabulary.js";
@@ -13,7 +15,7 @@ import { describedEndpoint, describedOrigin, describedTools } from "../described
 import { READ_ONLY, CALL_ADMISSION, CREDENTIAL, USAGE_GUIDE } from "./option-shapes.js";
 import { assertStaticToolNames } from "../tool-name.js";
 import { registerInvocationAuth } from "../invocation-auth.js";
-import { redactCatalog, redactSentSecrets, sentSecretsFetch, trackCredentialReads } from "../sent-secrets.js";
+import { redactCatalog, redactSentSecrets, sentSecretsFetch } from "../sent-secrets.js";
 import { callClassification } from "../call-classification.js";
 import { classifyTool } from "../tool-safety.js";
 import { closeProviderCall, enterProviderBoundary, inLogicalCall, knownProviderFailure, nestedProviderRequests, providerBoundary, providerCallContext, providerFetch, providerRequests, tracksRequests, } from "../provider-call.js";
@@ -24,7 +26,7 @@ export function defined(value) {
 }
 /**
  * Three things a hand-written surface is refused for at construction rather
- * than in production (#340): no description (discovery has nothing to route on
+ * than in production: no description (discovery has nothing to route on
  * and a guess costs a call), no explicit `readOnlyHint` (connecta never infers
  * the safety class, so an unclassified tool is a deployment bug), and an
  * `inputSchema` the validator cannot compile (declaring one is optional;
@@ -173,7 +175,7 @@ export function apiConnector(id, opts, oauth) {
         callTool: (name, args, ctx, options) => runEdge(core(name, args, ctx, options)),
     };
     const core = (name, args, ctx) => Effect.gen(function* () {
-        trackCredentialReads(ctx);
+        wrapViewCredentials(ctx);
         enterProviderBoundary(ctx, connector);
         const tool = byName.get(name);
         // Refusals before the handler runs are known failures: nothing was sent.
@@ -295,13 +297,15 @@ export function apiConnector(id, opts, oauth) {
     // This boundary's identity in a logical call, fixed now: this object with
     // this function, never whatever the property or a copy holds by then.
     providerBoundary(connector);
+    // Its catalog is authored here, so declared route descriptions follow each request's surface.
+    declaresRouteDescriptions(connector);
     registerCallEntry(connector, core);
     if (oauth)
         registerInvocationAuth(connector, async (ctx) => {
-            // The built-in static OAuth status only reads the stored grant. It never
-            // refreshes, invokes a handler, or sends a downstream request.
-            if ((await settleOnClose(ctx, () => oauth.status(ctx))).state === "auth_required") {
-                throw new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization. Call authorize_connector.`);
+            // The stored grant, as status reads it. Only a token about to expire is
+            // renewed, before any handler runs; nothing is sent to the API.
+            if ((await settleOnClose(ctx, () => oauth.prepareCall(ctx))).state === "auth_required") {
+                throw new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization. ${routePhrases(ctx).authorizeCall()}`);
             }
         });
     registerConnectorVocabulary(connector, opts.tools);