@zackbart/connecta 0.37.0 → 0.38.0

package/dist/types.d.ts

@@ -237,7 +237,7 @@ export interface ConnectorContext {
     /** Requested connector-operation deadline in milliseconds. */
     timeoutMs?: number;
 }
-type ConnectorStatusState = "ok" | "auth_required" | "credential_required" | "error";
+type ConnectorStatusState = "ok" | "per_caller" | "auth_required" | "credential_required" | "error";
 /** 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. */
@@ -248,6 +248,7 @@ export type ResourceTemplateRefusalCode = "resource_template_ambiguous" | "resou
 export interface ConnectorStatus {
     /** Distinct host-observed refusal codes, without URI or template text. */
     resourceTemplateRefusals?: ResourceTemplateRefusalCode[];
+    /** `per_caller` is non-error: caller-bound auth has no admitted caller to check. */
     state: ConnectorStatusState;
     /** When state === "auth_required", the URL the operator should open. */
     authorizationUrl?: string;
@@ -444,8 +445,8 @@ export interface Connector {
     consumeAuthError?(ctx: ConnectorContext): Promise<void>;
     /**
      * Optional: complete a downstream OAuth flow (called by
-     * /oauth/callback/<id>). `callbackParams` preserves the authorization
-     * server's RFC 9207 `iss` response parameter for validation. Built-in
+     * /oauth/callback/<id>). Declare only when the connector can exchange a code.
+     * `callbackParams` preserves the authorization server's RFC 9207 `iss` response parameter for validation. Built-in
      * OAuth adapters require a nonempty `state` in this parameter, including
      * programmatic calls and `api()` flows with PKCE disabled. Missing state
      * is refused before any downstream request.

package/dist/ui.js

@@ -1,5 +1,6 @@
 import { assertKnownOptions, keys, optionsOf } from "./config-schema.js";
 import { routeUi } from "./routes/ui.js";
+import { forwardsPrincipal } from "./request-principal.js";
 import { routeCredentials } from "./routes/credentials.js";
 import { routeOAuthManagement } from "./routes/oauth-management.js";
 import { uiData } from "./routes/ui-data.js";
@@ -60,6 +61,8 @@ export function uiProblemFor(connector, status, observed) {
     if (status === "error")
         return "connector_unavailable";
     if (status === "auth_required") {
+        if (forwardsPrincipal(connector))
+            return "caller_refused";
         if (connector.startAuth)
             return "oauth_required";
         return connector.credential ? "credential_required" : "auth_required";

package/dist/url-safety.js

@@ -117,10 +117,6 @@ export function classifyHost(hostname) {
         return "loopback";
     return "public";
 }
-/** True for loopback and private hosts alike. */
-export function isPrivateHost(hostname) {
-    return classifyHost(hostname) !== "public";
-}
 /**
  * Why connecta must not fetch `target`, a URL the downstream advertised, for a
  * connector configured at `configured` — or undefined when it may.

package/dist/usage-guide.js

@@ -84,8 +84,8 @@ Split remaining reads. Never replay writes for their output.
 
 ## Per-connector guides
 
-Fetch a listed guide with skills by its exact name, or \`connecta.skill(name)\`
-inside a program; it returns \`{ name, text, format: "text" }\`.
+Fetch a listed guide by its exact name with the skills tool, or
+\`connecta.skill(name)\` inside a program; it returns \`{ name, text, format: "text" }\`.
 \`guideRequired: true\` is a hard stop. connector_required and approval_required
 remain after schema expansion; schema_truncated clears after exact describe.
 Otherwise fetch for units, pagination, aliases, or sequences.

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.37.0";
+export declare const CONNECTA_VERSION = "0.38.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.37.0";
+export const CONNECTA_VERSION = "0.38.0";

package/dist/worker.js

@@ -47,7 +47,7 @@ function routeGuestImports(source) {
 export function workerExecutor(options) {
     // One pool per executor, so per isolate. A queued run may wait out one
     // default guest deadline: programs spend it awaiting host calls, and a
-    // five-second wait refused nearly every run queued behind one (#1106).
+    // five-second wait refused nearly every run queued behind one.
     const admission = new AdmissionController(options.admission ?? {
         concurrency: 2,
         maxQueueSize: 8,

package/documentation/README.md

@@ -36,20 +36,8 @@ The separate `@zackbart/connecta-eve` helper is available from 0.35.0. Its
 [package guide](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md)
 owns installation, supported Node/Eve versions, and token-source setup.
 
-## Audience rule
-
-`documentation/`, `templates/`, and `examples/worker/` are written first for an
-agent operating a deployment from the installed package. The root `README.md`
-and `guides/` explain the product for people and also ship in the package;
-they own no operator contracts. Operator conventions must be self-contained rules plus a
-neutral example. Decision records and issues explain why; no operator task
-requires them, `spec/`, `.claude/`, or the Connecta source checkout. Those
-three directories do not ship. Contributor source maps, INV citations, and
-implementation/test evidence belong under clearly labeled contributor
-headings and are optional for operators. Use `assistant`, `alice`, `bob`,
-`crm`, `tickets`, `notes_alice`, and `alice@example.com` in examples; never
-real deployment, client, person, or organization names. Maintained provider
-product names stay.
+For pre-0.29 storage or OAuth grants, complete the [retired layout migrations](./migration-retired-layouts.md)
+on 0.37.1 before upgrading past that bridge release.
 
 ## Contract reference
 
@@ -61,6 +49,7 @@ product names stay.
 | [Architecture (contributor reference)](./architecture.md)        | Request lifetimes, routes, storage, configuration, import boundaries, and Effect implementation               |
 | [Operator UI](./operator-ui.md)                                  | Optional UI setup, scoped configuration and live-data contract, activity disclosure, and UI implementation    |
 | [Operator UI tests (contributor reference)](./operator-tests.md) | Browser state matrix, real-server flows, and snapshot maintenance                                             |
+| [Retired layout migrations](./migration-retired-layouts.md)      | Required 0.37.1 bridge for KV, JSON state, and OAuth layout-2 grants                                          |
 | [Migration to 0.33](./migration-0.33.md)                         | Upgrade actions from 0.32 options to maintainers, members, agents, agent endpoints, and pool owners           |
 | [Provider migration for 0.29](./provider-migration-0.29.md)      | Upgrade actions for Notion, Vercel, and Cloudflare; provider reconciliation tables supply exact name mappings |
 | [Provider migration for 0.35](./provider-migration-0.35.md)      | Provider upgrade actions for 0.35.0                                                                           |
@@ -72,34 +61,9 @@ implementation evidence.
 
 ## Contributor reference
 
-### Documentation ownership
-
-The root [README](../README.md) explains the product for people. It owns what
-Connecta offers and the setup handoff. The human guides explain
-[how it works](../guides/how-it-works.md), [connecting agents](../guides/connecting-agents.md),
-and [safety and trust](../guides/safety-and-trust.md). Keep their examples small
-and consistent with these contracts. Configuration references, complete setup
-procedures, migrations, and internal module maps belong here in agent documentation.
-
-[AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md) is the
-canonical repository policy, with `CLAUDE.md` as its symlink. Do not copy its
-verification, review, or release rules into another policy document.
-
-Deployment-local READMEs and agent instructions own runnable platform setup:
-[Node and Docker](../templates/node/README.md), [Workers](../examples/worker/README.md).
-Keep those aligned with their configuration and with this task router.
-Repository [skills](https://github.com/zackbart/connecta/tree/main/.claude/skills)
-own scoped change procedures. Each [provider folder](https://github.com/zackbart/connecta/tree/main/src/providers)
-owns its maintained `SKILL.md`, options, tests, fixtures, and review data.
-Use those details instead of copying provider catalogs into general guides.
-The provider list in the human README is generated; preserve its marker pair
-and run `pnpm run check:providers-generated` after edits.
-
-When changing behavior, update its owning contract and task guide in the same
-change. Check examples against current source and point to the tests that
-defend the contract. Published Markdown links to repo-only files must use
-canonical `https://github.com/zackbart/connecta/blob/main/…` or `tree/main/…`
-links. Keep `documentation/` flat, with Markdown files only.
+For source changes, follow [AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md).
+Contributor references describe implementation and test evidence; deployment
+operators can use the task procedures above without a source checkout.
 
 The [changelog](../CHANGELOG.md) records shipped releases.
 [Decisions](https://github.com/zackbart/connecta/tree/main/decisions) explain