@zackbart/connecta 0.34.0 → 0.35.0

package/dist/types.d.ts

@@ -93,8 +93,8 @@ export interface ToolDef {
     outputSchema?: JsonSchema;
     /**
      * Standard MCP tool behavior hints plus provider-specific extensions.
-     * The registry classifies these after deployment overrides and provider
-     * review. Only a stored read verdict may use call_tool; program writes
+     * The registry classifies tools using deployment overrides and annotations.
+     * Only a stored read verdict may use call_tool; program writes
      * require a writable endpoint. Approval belongs to the host.
      */
     annotations?: ToolAnnotations;
@@ -238,67 +238,6 @@ export interface ConnectorContext {
     timeoutMs?: number;
 }
 type ConnectorStatusState = "ok" | "auth_required" | "credential_required" | "error";
-/**
- * What a reviewed downstream tool does. `"read"` is observational. `"write"`
- * changes state without destroying any that already exists, such as a create.
- * `"destructive"` modifies or removes existing state, including an upsert that
- * can overwrite. Both writes leave the read-only path; `"destructive"` also
- * asserts `destructiveHint`, which shapes the approval copy a human reads.
- */
-export type ToolVerdict = "read" | "write" | "destructive";
-/** One reviewed tool, with the evidence that justifies its verdict. */
-export interface ReviewedTool {
-    readonly verdict: ToolVerdict;
-    /** Why the verdict holds when the name or downstream annotations do not say. */
-    readonly reason?: string;
-    /**
-     * `sha256:<hex>` digest of the input and output schemas the review read.
-     * Omit until a review has actually read them; an invented digest reports
-     * drift that never happened. When the live schema no longer matches it, or
-     * it cannot be checked, the verdict lapses and the tool is served as a write.
-     */
-    readonly schemaDigest?: string;
-}
-/**
- * A reviewed classification of a downstream MCP catalog, keyed by exact tool
- * name. Plain data, validated at construction, so the same record classifies
- * live tools and feeds the drift check. A connector carries it as
- * `Connector.classification`, and the registry applies it on every read.
- *
- * It fails closed. A name it does not list keeps only an explicit downstream
- * read annotation; silence and contradiction classify as writes. A listed read
- * fills downstream silence but never overrules an explicit write annotation.
- * A listed write or destructive tool stays a write whatever the downstream
- * claims. A listed tool whose `schemaDigest` no longer matches is a write.
- */
-export interface ToolClassification {
-    /** Hide every name absent from tools, including tools claiming to be reads. */
-    readonly unlisted?: "hide";
-    readonly tools: Readonly<Record<string, ToolVerdict | ReviewedTool>>;
-}
-/**
- * How far a downstream catalog has moved away from the manifest a release
- * reviewed. Counts and nothing else: names, schemas, and prose stay out
- * of every surface this rides on, so a drift report can never become a payload
- * ([#343](https://github.com/zackbart/connecta/issues/343)).
- */
-export interface CatalogDriftCounts {
-    /** Downstream tools dropped because their names contain C0, DEL, or C1. */
-    droppedTools?: number;
-    /** Live tools no release classified. Each one fails closed at call time. */
-    unclassifiedTools: number;
-    /** Classified names this catalog no longer serves — plan gating included. */
-    unservedTools: number;
-    /** Explicit downstream annotations that contradict a vetted verdict. */
-    annotationConflicts: number;
-    /** Tools whose reviewed schema digest no longer matches what arrived. */
-    schemaChanges: number;
-}
-/** One drift observation, taken while serving a catalog refresh. */
-export interface CatalogDriftReport extends CatalogDriftCounts {
-    /** When the observation was taken; never when a probe was scheduled. */
-    observedAt: string;
-}
 /** The last agent-facing catalog read this runtime served for one connector. */
 export interface CatalogAccessObservation {
     /** Fresh means the read used a live or unexpired catalog; stale means SWR. */
@@ -334,7 +273,6 @@ export interface ConnectorStatus {
      * observation is not persisted the way the catalog is, so absence means this
      * isolate or process has seen nothing, not that nothing drifted.
      */
-    catalogDrift?: CatalogDriftReport;
     /**
      * The last agent-facing catalog read in this runtime. This payload-free
      * observation is not persisted and operator reads do not replace it.
@@ -364,6 +302,8 @@ export type ConnectorSkillResourceContents = {
 });
 /** The whole plugin contract — the one open seam. */
 export interface Connector {
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     id: string;
     /**
      * Who owns this connector's downstream authentication. `shared` keeps one
@@ -398,7 +338,7 @@ export interface Connector {
      * cross-operation sequencing rule).
      *
      * Served as `skill://connecta/connectors/<slug>/SKILL.md`, with generated
-     * frontmatter followed by the unchanged guide body. `connector:<id>` is a
+     * frontmatter, a read-only policy notice when configured, and the guide body. `connector:<id>` is a
      * one-release lookup alias. The guide remains deployment-owned configuration;
      * no runtime registration or shared mutable copy exists.
      */
@@ -425,35 +365,6 @@ export interface Connector {
      * fetched lazily over the network and are not known at construction time.
      */
     staticTools?: ToolDef[];
-    /**
-     * Optional reviewed classification of the tools `listTools` returns: data
-     * the registry applies, never something the connector applies itself.
-     * `remoteMcp({ classify })` and maintained providers set it to a
-     * deep-frozen record; a custom connector may set one too. It is validated
-     * when a registry first reads it (INV-11), and read once per connector
-     * object. A connector that sets it lists raw downstream tools; the
-     * registry caches and persists only that listing, and classifies it on
-     * every read with this record, so no cache layer carries a verdict.
-     * Connectors with `staticTools` cannot set it: annotate those directly.
-     *
-     * A wrapper that rebuilds a connector must forward this field to keep the
-     * review. `{ ...connector }`, `Object.assign`, and `Object.create` keep it;
-     * a forwarding class that omits it serves an unreviewed connector, whose
-     * downstream annotations are its own claims and fail closed when absent.
-     * Deployment-level classifier overrides, keyed by connector id
-     * and tool ([#706](https://github.com/zackbart/connecta/issues/706)), apply
-     * regardless of wrapping.
-     */
-    readonly classification?: ToolClassification | undefined;
-    /**
-     * Optional: the drift this connector saw the last time it listed tools,
-     * or undefined when it has not listed any yet. A getter over an
-     * observation, never a probe: calling it makes no request, touches no
-     * credential, and returns counts only. Ignored for a connector with a
-     * `classification`, whose drift the registry observes itself, against
-     * that record, while serving a refresh the deployment already asked for.
-     */
-    catalogDrift?(): CatalogDriftReport | undefined;
     /**
      * Optional: what this connector is, for `Connecta.describeConfig()` and the
      * operator surfaces built on it — where it points, how it authenticates,
@@ -582,7 +493,7 @@ export interface ConnectorToolDescription {
     annotations?: ToolAnnotations;
     inputSchema?: JsonSchema;
     outputSchema?: JsonSchema;
-    /** Present on registry descriptions after overrides and provider review (INV-1). */
+    /** Present on registry descriptions after overrides and annotations (INV-1). */
     classification?: "read" | "write";
 }
 /** What `Connector.describe()` reports. Every field is optional but `source`. */
@@ -605,7 +516,7 @@ export interface ConnectorDescription {
     tools?: ConnectorToolDescription[];
 }
 export interface ConnectorUsageGuide {
-    /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
+    /** Markdown served by `skills`, with a policy notice when the connector is read-only. */
     content: string;
     /**
      * Discovery hint describing the conventions the guide covers. Whitespace is
@@ -728,7 +639,7 @@ export type AuthResult = {
     /** Human owner represented by a non-interactive access credential. */
     principal?: IdentityReference;
     /**
-     * Declared agent name. Only the built-in `accessTokens()` adapter may
+     * Declared agent name. Only built-in agent credential adapters may
      * set it; a result from any other provider that carries it is refused.
      */
     agent?: string;
@@ -754,7 +665,7 @@ export interface AuthenticatedIdentity {
     principal?: IdentityReference;
     /**
      * Name of the code-declared agent this caller is, from `agents`. Set only
-     * when the built-in access-token adapter admitted a `cta_` token bound to
+     * when a built-in agent adapter admitted a credential bound to
      * a currently declared agent; an agent never has a `principal`.
      */
     agent?: string;
@@ -918,8 +829,9 @@ export interface InboundAuth {
      * Best-effort friendly label for a stable activity actor id. Called only
      * while serving an authorized activity read, never during tool admission or
      * event writes. The result is display-only and cannot grant access.
+     * Stop request-owned work when signal aborts (reader left or label budget expired).
      */
-    activityActorLabel?(subjectId: string): string | undefined | Promise<string | undefined>;
+    activityActorLabel?(subjectId: string, signal?: AbortSignal): string | undefined | Promise<string | undefined>;
     /**
      * Optional browser sign-in configuration. When present, operator pages use
      * the provider's interactive sign-in flow.

package/dist/upward.js

@@ -0,0 +1,3 @@
+export function* upwardStep(effect) {
+    return yield effect;
+}

package/dist/usage-guide.js

@@ -19,6 +19,8 @@ Discover and call together when schemas suffice. search_tools covers catalog
 inspection. On a read-only endpoint, as execute_code's description says, search
 omits writes (guides may name them) and each fails read_only_endpoint; tell the
 user. Unannotated tools fail closed to writes.
+For a requested write, make the call through the write route; the host may ask
+the user to confirm it. Connecta classifies and routes writes; the host owns approval.
 
 ## The global and the envelopes
 
@@ -113,7 +115,7 @@ async () => {
 }
 \`\`\`
 
-Oversized returns lead with nextAction. Never rerun writes for output. write_outcome_unknown forbids retry, even if caught.
+Oversized returns lead with nextAction. Never rerun writes for output. write_outcome_unknown or writeOutcome forbids retry, even if caught.
 Recovery args may be partial (argsRedacted) or absent (argsOmitted). Reconcile
 before retrying with the original args or repeating a program that sent writes.
 Non-retryable errors need repair.

package/dist/validate.d.ts

@@ -29,6 +29,8 @@ export interface CompileValidatorOptions {
      */
     address: string;
 }
+/** Optional in-process properties have the same absence semantics as JSON input. Never mutate the caller. */
+export declare function normalizeToolInput<A>(value: A): A;
 /**
  * Validate call arguments against a tool's JSON Schema.
  *
@@ -39,8 +41,8 @@ export interface CompileValidatorOptions {
  * convention arguments (a `confirm` flag on writes, say) that individual tool
  * schemas do not declare before deciding the call is really invalid.
  *
- * A schema the validator cannot compile (or that only fails on first use, e.g.
- * an unresolvable `$ref`) is warned about once and then passed through — a
+ * A schema the validator cannot compile (or evaluate, e.g. an unresolvable
+ * `$ref`) is warned about once and the failing call is passed through — a
  * broken schema should not break an otherwise working tool. Pass
  * `failClosed: true` to instead reject such calls with `invalid_args`, for
  * callers that would rather refuse a call than forward unvalidated arguments.

package/dist/validate.js

@@ -3,11 +3,67 @@ import { boundedEchoText, ConnectorCallError } from "./errors.js";
 import { MAX_ARGUMENT_VALIDATION_ISSUES } from "./errors.js";
 import { failureRecord, logFailure } from "./operator-record.js";
 // Lazy validator cache keyed by the schema object itself; null marks a schema
-// the validator rejected (warned once, then passed through rather than
-// breaking a working tool). A WeakMap so schemas belonging to a discarded
+// the validator could not compile (warned once, then passed through rather
+// than breaking a working tool). A WeakMap so schemas belonging to a discarded
 // connector are collectable, the same pattern compactSchema uses.
 const validators = new WeakMap();
+const evaluationWarnings = new WeakSet();
 const REQUIRED_PROPERTY_RE = /^Instance does not have required property "([^"]+)"\.$/;
+function plainContainer(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return true;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** Optional in-process properties have the same absence semantics as JSON input. Never mutate the caller. */
+export function normalizeToolInput(value) {
+    // Keep unchanged inputs and their pass-through subtrees by identity. JSON
+    // callers have nothing to omit, so they never need a copy.
+    const seen = new WeakSet();
+    const remaining = [value];
+    let needed = false;
+    while (remaining.length > 0) {
+        const item = remaining.pop();
+        if (!plainContainer(item) || seen.has(item))
+            continue;
+        seen.add(item);
+        for (const child of Object.values(item)) {
+            if (child === undefined && !Array.isArray(item))
+                needed = true;
+            else if (child !== null && typeof child === "object")
+                remaining.push(child);
+        }
+    }
+    if (!needed)
+        return value;
+    const copies = new WeakMap();
+    const pending = [];
+    const copy = (item) => {
+        if (!plainContainer(item))
+            return item;
+        const existing = copies.get(item);
+        if (existing)
+            return existing;
+        const target = Array.isArray(item) ? [] : Object.create(Object.getPrototypeOf(item));
+        if (Array.isArray(item))
+            target.length = item.length;
+        copies.set(item, target);
+        pending.push([item, target]);
+        return target;
+    };
+    const root = copy(value);
+    for (let next = pending.pop(); next; next = pending.pop()) {
+        const [source, target] = next;
+        for (const [key, item] of Object.entries(source)) {
+            if (item === undefined && !Array.isArray(source))
+                continue;
+            Object.defineProperty(target, key, { value: copy(item), enumerable: true, configurable: true, writable: true });
+        }
+    }
+    return root;
+}
 const CONTAINER_VALIDATION_KEYWORDS = new Set([
     "properties",
     "items",
@@ -458,8 +514,8 @@ function disableValidation(schema, subject, logger, err) {
  * convention arguments (a `confirm` flag on writes, say) that individual tool
  * schemas do not declare before deciding the call is really invalid.
  *
- * A schema the validator cannot compile (or that only fails on first use, e.g.
- * an unresolvable `$ref`) is warned about once and then passed through — a
+ * A schema the validator cannot compile (or evaluate, e.g. an unresolvable
+ * `$ref`) is warned about once and the failing call is passed through — a
  * broken schema should not break an otherwise working tool. Pass
  * `failClosed: true` to instead reject such calls with `invalid_args`, for
  * callers that would rather refuse a call than forward unvalidated arguments.
@@ -494,18 +550,24 @@ export function validateCatalogToolInput(schema, args, opts, subject) {
             validator = null;
         }
     }
-    // A schema the validator could not compile (or that a prior call disabled):
+    // A schema the validator could not compile:
     // pass through by default, refuse when the caller opted into fail-closed.
     if (validator === null) {
         return opts.failClosed ? unevaluableSchema(opts.address) : null;
     }
     let result;
     try {
+        args = normalizeToolInput(args);
         result = validator.validate(args);
     }
     catch (err) {
-        // e.g. an unresolvable $ref — surfaces on first validate, not compile.
-        disableValidation(schema, subject, logger, err);
+        // Evaluation can fail on an instance (unsupported JS values or cycles),
+        // not just a lazy schema reference. Never disable a compiled validator
+        // because of one call's input; subsequent valid calls must still validate.
+        if (!evaluationWarnings.has(schema)) {
+            evaluationWarnings.add(schema);
+            logFailure(logger, "input schema unusable; arguments are not validated", failureRecord(subject, err));
+        }
         return opts.failClosed ? unevaluableSchema(opts.address) : null;
     }
     if (result && !result.valid) {
@@ -514,9 +576,24 @@ export function validateCatalogToolInput(schema, args, opts, subject) {
         // Told from the reviewed findings, never the validator's own sentences,
         // which quote the schema's types, enums, and patterns.
         const validation = validationDetails(schema, units);
-        const shown = nestedUnits.length > 0 ? validationDetails(schema, nestedUnits) : validation;
+        const limit = schema.properties?.limit?.enum;
+        const supplied = args !== null && typeof args === "object" ? args["limit"] : undefined;
+        const discreteLimit = supplied !== undefined &&
+            Array.isArray(limit) &&
+            limit.length > 0 &&
+            limit.length <= 8 &&
+            limit.every((size) => Number.isSafeInteger(size) && Number(size) > 0) &&
+            !limit.includes(supplied);
+        const otherUnits = units.filter((unit) => unit.instanceLocation !== "#/limit");
+        const otherIssues = otherUnits.length > 0;
+        const shown = discreteLimit
+            ? validationDetails(schema, otherUnits)
+            : nestedUnits.length > 0
+                ? validationDetails(schema, nestedUnits)
+                : validation;
         const detail = boundedEchoText(shown.issues.map((issue) => `${issue.path}: expected ${issue.expected} (${issue.code})`).join("; "), 256);
-        return new ConnectorCallError("invalid_args", `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`, { validation, repair: repairDetails(schema, args, units, validator) });
+        const ordinary = `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`;
+        return new ConnectorCallError("invalid_args", discreteLimit ? `The limit must be one of ${limit.join(", ")}.${otherIssues ? ` ${ordinary}` : ""}` : ordinary, { validation, repair: repairDetails(schema, args, units, validator) });
     }
     return null;
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.34.0";
+export declare const CONNECTA_VERSION = "0.35.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.34.0";
+export const CONNECTA_VERSION = "0.35.0";