@spacefast/common 0.2.2 → 0.4.1

package/dist/contracts/connectors.js

@@ -0,0 +1,941 @@
+// Connectors: team-scoped integrations over the Executor engine. One connector
+// is a tool source (an OpenAPI spec, a GraphQL endpoint, a remote MCP server);
+// one connection is a configured, optionally authenticated instance of it; one
+// run is a single execution — a tool call or a code program — with one status
+// machine and one resume path.
+//
+// Two rules this file exists to enforce on the wire:
+//
+//   - SECRETS NEVER LEAVE THE CONTROL PLANE. Credentials are write-only:
+//     accepted on create, never returned. Reads expose `credentialConfigured`,
+//     the way `RepositoryConnectionSchema` does — never the value, never the
+//     ciphertext, never a masked preview a client could be tempted to parse.
+//   - ONE ADDRESS GRAMMAR. A tool is `<connectionId>/<tool>`. The engine's
+//     five-segment addresses and its
+//     `org|user` owner vocabulary stop at the module boundary and never appear
+//     on our wire.
+//
+// `operationId` lives in `detail:` on the route, not here. Problem codes live in
+// `contracts/error-codes.ts`, the one flat table.
+import { z } from "zod";
+import { AnyObjectSchema, CursorPaginationSchema, ProblemDetailsSchema, cursorListQuerySchema, dataEnvelope, mutationEnvelope, } from "./common.js";
+// ---------------------------------------------------------------------------
+// Enums.
+// ---------------------------------------------------------------------------
+export const connectorSourceKindSchema = z
+    .enum(["openapi", "graphql", "mcp"])
+    .describe("The kind of tool source a connector reads: an OpenAPI spec, a GraphQL endpoint, or a remote MCP server.");
+export const connectionOwnerSchema = z
+    .enum(["team", "personal"])
+    .describe("`team` is shared with everyone on the team; `personal` is yours, and only within this team — connecting the same account for another team is another connection.");
+// Derived on read from the engine's last health probe, token expiry, any pending
+// authorization session, and our `revokedAt` tombstone. There is no status
+// column, so a status can never go stale against the thing it describes.
+export const connectionStatusSchema = z
+    .enum(["pending_authorization", "active", "degraded", "needs_reauth", "revoked"])
+    .describe("Derived connection state. Never stored, so it cannot drift from the credential it describes.");
+export const toolSafetySchema = z
+    .enum(["read_only", "write", "destructive"])
+    .describe("What the tool does to the far side, read from the source spec. Not configurable.");
+export const policyActionSchema = z
+    .enum(["approve", "require_approval", "block"])
+    .describe("What policy does with a call: run it, park it for a person, or refuse it.");
+export const runStatusSchema = z
+    .enum(["running", "awaiting_approval", "succeeded", "failed", "expired"])
+    .describe("Where a run is in its one status machine.");
+export const runInputKindSchema = z
+    .enum(["tool", "code"])
+    .describe("`tool` is one call; `code` is a program that may make many. Same endpoint, same id space, same resume.");
+export const catalogEntryKindSchema = z
+    .enum(["preset", "registry", "team"])
+    .describe("Where a catalog row came from: a curated preset, the public registry, or this team's own connectors.");
+// ---------------------------------------------------------------------------
+// Shared building blocks.
+// ---------------------------------------------------------------------------
+export const AuthMethodSchema = z
+    .discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("api_key"),
+        slug: z.string().describe("Names this method when a connector offers more than one."),
+        label: z.string().describe("What to call it in a connect form, in the provider's own words."),
+    }),
+    z.object({
+        kind: z.literal("oauth2"),
+        slug: z.string().describe("Names this method when a connector offers more than one."),
+        label: z.string().describe("What to call it in a connect form, in the provider's own words."),
+        scopes: z
+            .array(z.string())
+            .describe("Scopes requested at authorization unless the caller narrows them."),
+        clientIdMetadataDocument: z
+            .boolean()
+            .optional()
+            .describe("Whether the provider supports public clients identified by a metadata-document URL."),
+        dynamicRegistration: z
+            .boolean()
+            .describe("Whether the provider supports RFC 7591 dynamic client registration, so no client has to be pre-created."),
+    }),
+    z.object({
+        kind: z.literal("none"),
+        slug: z.string().describe("Names this method when a connector offers more than one."),
+        label: z.string().describe("What to call it in a connect form."),
+    }),
+    z.object({
+        kind: z.literal("first_party"),
+        slug: z.string().describe("Names this method when a connector offers more than one."),
+        label: z.string().describe("What to call it in a connect form."),
+        provider: z
+            .string()
+            .describe("Existing Spacefast credential this connector borrows, e.g. the GitHub App installation. Nothing to enter."),
+    }),
+])
+    .describe("One way to authenticate a connector. A connector may offer several, so a connect call names the one it means.");
+// What the provider calls the key, where to mint it, and anything you have to do
+// first. Passthrough from the registry's per-domain credential docs — every
+// field is free-form and may be missing, so this renders next to the field
+// asking for the value instead of sending people off to search.
+export const CredentialGuidanceSchema = z
+    .object({
+    label: z
+        .string()
+        .nullable()
+        .describe('What the provider calls this credential, e.g. "Personal access token".'),
+    mintUrl: z
+        .string()
+        .nullable()
+        .describe("Page on the provider where the credential is created."),
+    docsUrl: z.string().nullable().describe("Provider documentation for this credential."),
+    notes: z
+        .string()
+        .nullable()
+        .describe("Setup notes: prerequisites, plan requirements, scopes to tick."),
+    steps: z
+        .array(z.string())
+        .describe("Ordered steps to get the credential, when the provider spells them out."),
+})
+    .describe("Provider-supplied help for one credential, shown next to the field asking for it.");
+export const connectorCredentialGuidanceResponseSchema = dataEnvelope(z.array(CredentialGuidanceSchema)).describe("Per-provider credential guidance for the connect modal; empty when the registry knows none.");
+export const ConnectorFieldSchema = z
+    .object({
+    name: z.string().describe("Field key to send back in `credential.values`."),
+    required: z
+        .boolean()
+        .optional()
+        .describe("Whether this field must be filled before connecting. Defaults to true."),
+    label: z.string().describe("What to show above the input."),
+    secret: z
+        .boolean()
+        .describe("Whether the value is a secret: mask it in UI, never log it, never echo it back."),
+    guidance: CredentialGuidanceSchema.nullable().describe("Provider help for this field, when the registry has any."),
+})
+    .describe("One value a connector needs before it can connect.");
+// ---------------------------------------------------------------------------
+// Resources.
+// ---------------------------------------------------------------------------
+export const ConnectionSchema = z
+    .object({
+    id: z
+        .string()
+        .describe("Connection id (`cxn_`). This is also the first segment of every tool address it owns."),
+    connector: z.string().describe("Slug of the connector this connection authenticates."),
+    owner: connectionOwnerSchema,
+    serving: z.boolean().default(false),
+    displayName: z.string().describe('What people call this connection, e.g. "Linear (support)".'),
+    description: z
+        .string()
+        .nullable()
+        .describe("Agent-visible note on what this connection is for. Shown to models choosing between several."),
+    status: connectionStatusSchema,
+    identityLabel: z
+        .string()
+        .nullable()
+        .describe("Account label reported by the provider, when it identifies itself. Null until the first successful probe."),
+    credentialConfigured: z
+        .boolean()
+        .describe("Whether a usable credential is stored. The credential itself is never returned by any endpoint."),
+    authMethod: z
+        .string()
+        .nullable()
+        .describe("Slug of the connector auth method this connection used."),
+    scopes: z
+        .array(z.string())
+        .describe("Scopes actually granted, when the provider reports them."),
+    isDefault: z
+        .boolean()
+        .describe("Whether this is the connection an agent gets when it names the connector alone."),
+    toolCount: z
+        .number()
+        .int()
+        .describe("Tools reachable through this connection at the last sync."),
+    createdBy: z
+        .string()
+        .nullable()
+        .describe("User who connected it; null for first-party connections Spacefast owns."),
+    lastCheckedAt: z.string().datetime().nullable().describe("Last health probe."),
+    revokedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("When it was disconnected. The credential is purged; the row tombstones."),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+})
+    .describe("A configured instance of a connector, with a credential the control plane holds and never hands out.");
+export const connectorCatalogSourceSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("openapi"), spec: z.string(), baseUrl: z.string().optional() }),
+    z.object({ kind: z.literal("graphql"), endpoint: z.string() }),
+    z.object({ kind: z.literal("mcp"), endpoint: z.string() }),
+]);
+export const ConnectorSchema = z
+    .object({
+    slug: z
+        .string()
+        .describe("Stable, team-unique connector slug. Also the namespace tools hang off."),
+    title: z.string().describe("Display name, seeded from the source spec."),
+    description: z
+        .string()
+        .nullable()
+        .describe("What this connector reaches, in one line. Agent-visible."),
+    source: connectorSourceKindSchema,
+    catalogSource: connectorCatalogSourceSchema
+        .optional()
+        .describe("Stored spec or endpoint for execution catalog discovery. No credentials."),
+    sourceUrl: z
+        .string()
+        .nullable()
+        .describe("Spec, endpoint, or MCP URL this connector was built from; null when it was registered from an inline spec."),
+    firstParty: z
+        .boolean()
+        .describe("Built into Spacefast. First-party connectors cannot be edited or removed."),
+    presetId: z
+        .string()
+        .nullable()
+        .describe("Curated preset this connector was created from, when it came from the catalog."),
+    authMethods: z
+        .array(AuthMethodSchema)
+        .describe("Every way this connector can be authenticated."),
+    toolCount: z.number().int().describe("Tools this connector exposes after the last spec sync."),
+    connections: z
+        .array(ConnectionSchema)
+        .describe("Connections the calling credential may use — not every connection that exists on this connector."),
+    specSyncedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("Last time the source was fetched and tools rebuilt."),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+})
+    .describe("A tool source registered for one team.");
+export const PolicyDecisionSchema = z
+    .object({
+    ruleId: z.string().describe("Policy rule that decided it."),
+    pattern: z.string().describe("The pattern that matched."),
+    owner: connectionOwnerSchema.describe("Whose rule it is. Team rules are a floor members cannot loosen."),
+})
+    .describe("The rule that answered for an address. One shape wherever an effect is explained.");
+export const ToolSchema = z
+    .object({
+    address: z
+        .string()
+        .describe("`<connectionId>/<tool>` — the one address grammar. Pass this straight to a connector run."),
+    name: z.string().describe("Tool name within its connector."),
+    summary: z.string().describe("One line on what the tool does, from the source spec."),
+    safety: toolSafetySchema,
+    effect: policyActionSchema.describe("What actually happens when an agent calls this, after policy resolution."),
+    decidedBy: PolicyDecisionSchema.nullable().describe("The rule behind `effect`; null when nothing matched and the spec's own default applied."),
+    inputSchema: AnyObjectSchema.describe("JSON Schema for the tool's arguments."),
+})
+    .describe("One callable tool, already resolved against policy so a caller knows the answer before it calls.");
+export const PolicyRuleSchema = z
+    .object({
+    id: z
+        .string()
+        .describe("Policy rule id. Opaque — minted by the policy engine, not a Spacefast resource prefix."),
+    pattern: z
+        .string()
+        .describe("`*`, `<connector>/*`, `<connectionId>/*`, or `<connectionId>/<tool>`. First match in order wins."),
+    action: policyActionSchema,
+    owner: connectionOwnerSchema.describe("Team rules are a floor: a personal rule may tighten one, never loosen it."),
+    position: z
+        .string()
+        .describe("Fractional index the engine assigned from the pattern's specificity. Rules evaluate in this order."),
+    createdAt: z.string().datetime(),
+})
+    .describe("One ordered address-pattern rule. Most restrictive across owners wins.");
+export const PolicyResolutionSchema = z
+    .object({
+    address: z.string().describe("The address that was resolved."),
+    effect: policyActionSchema.describe("What would happen if you called it right now."),
+    decidedBy: PolicyDecisionSchema.nullable().describe("The rule that decided it; null when the spec default applied."),
+    explanation: z.string().describe("Why, in a sentence you can put in front of a person."),
+})
+    .describe('"What happens if I call this, and why" — the answer without making the call.');
+export const PendingApprovalSchema = z
+    .object({
+    decisionId: z
+        .string()
+        .nullable()
+        .describe("Grant-decision id (`gdc_`) backing this approval when the credential is grant-backed; null for session/API-key pauses (resume with the run id)."),
+    mode: z
+        .enum(["human", "model"])
+        .describe("Who may decide. Fixed when the run parked: `human` refuses machine resumes."),
+    address: z.string().describe("Tool the run is waiting to call."),
+    preview: AnyObjectSchema.describe("The arguments it would send, with secret-shaped values masked."),
+    reason: z
+        .enum(["policy_require_approval", "annotation_requires_approval"])
+        .describe("Why it parked: a policy rule, or the tool's own annotation."),
+    matchedPattern: z
+        .string()
+        .nullable()
+        .describe("Policy pattern that parked it; null when the tool asked for itself."),
+    approvalUrl: z.string().url().describe("Dashboard page where a person approves or denies."),
+    expiresAt: z.string().datetime().describe("After this the run expires and cannot be resumed."),
+})
+    .describe("A run waiting on a decision. Durable — any replica can resume it.");
+export const ConnectorRunInputSummarySchema = z
+    .object({
+    kind: runInputKindSchema,
+    address: z
+        .string()
+        .nullable()
+        .describe("Tool address for a `tool` run; null for a `code` program."),
+    digest: z
+        .string()
+        .describe("Content digest of the submitted input, so a retry can be recognized without replaying it."),
+})
+    .describe("What the run was asked to do, without echoing arguments that may carry customer data.");
+export const ConnectorRunUsageSchema = z
+    .object({
+    toolCalls: z.number().int().describe("Tool calls made so far."),
+    egressBytes: z.number().int().describe("Bytes read from third-party APIs so far."),
+    durationMs: z.number().int().describe("Wall-clock time spent executing so far."),
+})
+    .describe("What this run has spent. Budgets are enforced against these numbers.");
+export const CONNECTOR_RUN_ORIGINS = [
+    "dashboard",
+    "cli",
+    "api",
+    "mcp",
+    "zero",
+    "function",
+    "system",
+];
+export const connectorRunOriginSchema = z.enum(CONNECTOR_RUN_ORIGINS);
+const connectorRunBaseSchema = z.object({
+    origin: connectorRunOriginSchema,
+    space: z.string().nullable().describe("Space id that initiated this run, if any."),
+    handler: z.string().nullable().describe("Runtime handler that initiated this run, if any."),
+    visitor: z.boolean().describe("Whether a signed-in Space visitor initiated this run."),
+    id: z.string().describe("Run id (`cxr_`)."),
+    input: ConnectorRunInputSummarySchema,
+    usage: ConnectorRunUsageSchema,
+    createdAt: z.string().datetime(),
+});
+// `status` is the discriminant. `result` exists only on `succeeded`, `error`
+// only on `failed`, `approval` only on `awaiting_approval` — a discriminated
+// union rather than five optional fields, so a client cannot read a result off a
+// failure and the generated SDK narrows correctly.
+export const ConnectorRunSchema = z
+    .discriminatedUnion("status", [
+    connectorRunBaseSchema.extend({
+        status: z
+            .literal("running")
+            .describe("Still executing. Poll the run, or submit the next one with a longer `waitMs`."),
+    }),
+    connectorRunBaseSchema.extend({
+        status: z.literal("awaiting_approval").describe("Parked on a decision."),
+        approval: PendingApprovalSchema,
+    }),
+    connectorRunBaseSchema.extend({
+        status: z.literal("succeeded"),
+        completedAt: z.string().datetime(),
+        result: z.unknown().describe("Whatever the tool or program returned."),
+    }),
+    connectorRunBaseSchema.extend({
+        status: z.literal("failed"),
+        completedAt: z.string().datetime(),
+        error: ProblemDetailsSchema.describe("Why it failed, as a problem document. The HTTP response is still 200: the request succeeded, the run did not."),
+    }),
+    connectorRunBaseSchema.extend({
+        status: z
+            .literal("expired")
+            .describe("Parked too long. Submit it again; it cannot be resumed."),
+        completedAt: z.string().datetime(),
+    }),
+])
+    .describe("One execution. A tool call and a code program are the same resource.");
+export const ConnectionHealthSchema = z
+    .object({
+    connectionId: z.string(),
+    status: connectionStatusSchema.describe("State after this probe."),
+    reachable: z.boolean().describe("Whether the provider answered."),
+    latencyMs: z
+        .number()
+        .int()
+        .nullable()
+        .describe("Round trip of the probe; null when it never got an answer."),
+    detail: z.string().nullable().describe("What went wrong, when something did."),
+    toolCount: z.number().int().describe("Tools reachable right now."),
+    checkedAt: z.string().datetime(),
+})
+    .describe("A live probe of one connection. Token refresh happens automatically; this only reports.");
+// ---------------------------------------------------------------------------
+// Catalog.
+// ---------------------------------------------------------------------------
+// One row per addable surface, never one row with badges: a service with both an
+// API and an MCP server is two rows, each naming its surface ("Stripe API",
+// "Stripe MCP"). Facets are the surface kind, not an invented category tree.
+export const ConnectorCatalogEntrySchema = z
+    .object({
+    id: z
+        .string()
+        .describe("Stable id for this row. Pass it to registration as `presetId` for a one-click add."),
+    kind: catalogEntryKindSchema,
+    surface: connectorSourceKindSchema.describe("Which surface this row adds. The one facet the picker offers."),
+    title: z.string().describe('Service name plus surface, e.g. "Stripe MCP".'),
+    description: z.string().nullable().describe("One line on what the service does."),
+    domain: z
+        .string()
+        .nullable()
+        .describe("Provider domain, e.g. `stripe.com`. Null for rows with no public domain."),
+    logoUrl: z
+        .string()
+        .nullable()
+        .describe("Spacefast-proxied logo path. Never a third-party URL — the browser must not call the registry directly."),
+    presetId: z.string().nullable().describe("Curated preset backing this row, when one does."),
+    registryId: z.string().nullable().describe("Registry entry backing this row, when one does."),
+    family: z
+        .string()
+        .nullable()
+        .describe("Grouping key for services that ship many slices, e.g. Google or Microsoft Graph."),
+    featured: z.boolean().describe("Whether to surface this row before the long tail."),
+    authHint: z
+        .array(AuthMethodSchema)
+        .describe("Authentication the row is expected to need, so the connect form is right on the first render."),
+    credentialGuidance: CredentialGuidanceSchema.nullable().describe("Per-domain credential help, when the registry has any."),
+    alreadyAdded: z.boolean().describe("Whether this team already registered this surface."),
+    connectorSlug: z
+        .string()
+        .nullable()
+        .describe("The team connector this row resolves to when `alreadyAdded`; null otherwise."),
+})
+    .describe("One addable surface in the merged catalog: curated presets, the public registry, and the team's own connectors.");
+export const connectorCatalogQuerySchema = cursorListQuerySchema.extend({
+    query: z
+        .string()
+        .trim()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("Free-text filter over title, description, and domain."),
+    surface: connectorSourceKindSchema.optional().describe("Show only rows adding this surface."),
+    kind: catalogEntryKindSchema.optional().describe("Show only rows from this source."),
+});
+// ---------------------------------------------------------------------------
+// Connector requests.
+// ---------------------------------------------------------------------------
+export const connectorSourceSchema = z
+    .discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("openapi"),
+        specUrl: z.string().url().optional().describe("URL of the OpenAPI document to fetch."),
+        spec: AnyObjectSchema.optional().describe("Inline OpenAPI document, when there is no URL to fetch."),
+        baseUrl: z.string().url().optional().describe("Override the server URL the spec declares."),
+    })
+        .refine((value) => Boolean(value.specUrl) !== Boolean(value.spec), {
+        message: "Give exactly one of specUrl or spec.",
+    }),
+    z.object({
+        kind: z.literal("graphql"),
+        endpoint: z.string().url().describe("GraphQL endpoint to introspect."),
+    }),
+    z.object({
+        kind: z.literal("mcp"),
+        endpoint: z
+            .string()
+            .url()
+            .describe("Remote MCP endpoint. stdio servers cannot be reached from a hosted product."),
+    }),
+])
+    .describe("Where the tools come from.");
+/**
+ * Slugs owned by dashboard routes or the built-in Spacefast MCP integration.
+ * Registration rejects them before a connector can shadow an existing namespace.
+ */
+export const CONNECTOR_RESERVED_SLUGS = [
+    "add",
+    "browse",
+    "catalog",
+    "connections",
+    "detect",
+    "policies",
+    "runs",
+    "spacefast",
+    "tools",
+];
+export const connectorRegisterSchema = z
+    .object({
+    slug: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "Use lowercase letters, digits, and dashes.")
+        .refine((slug) => !CONNECTOR_RESERVED_SLUGS.some((reserved) => reserved === slug), {
+        message: "This slug is reserved.",
+    })
+        .describe("Team-unique slug. Also the namespace its tools hang off, so keep it short."),
+    title: z
+        .string()
+        .min(1)
+        .max(255)
+        .describe("Display name. Defaults to whatever the source calls itself."),
+    description: z
+        .string()
+        .max(1_000)
+        .optional()
+        .describe("What this connector reaches, in one line. Agent-visible."),
+    presetId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Catalog row to add. Skips fetching and analyzing the source — everything else is optional when set."),
+    source: connectorSourceSchema
+        .optional()
+        .describe("Required unless `presetId` names a catalog row that carries it."),
+    authMethods: z
+        .array(AuthMethodSchema)
+        .optional()
+        .describe("Omit to derive authentication from the source's own declared security schemes."),
+    specOverrides: z
+        .array(AnyObjectSchema)
+        .max(200)
+        .optional()
+        .describe("RFC 6902 JSON Patch operations applied to the fetched spec before tools are built."),
+})
+    .refine((value) => Boolean(value.presetId) || Boolean(value.source), {
+    message: "Give a source, or a presetId that carries one.",
+});
+export const connectorPatchSchema = z
+    .object({
+    title: z.string().min(1).max(255).optional().describe("Replacement display name."),
+    description: z
+        .string()
+        .max(1_000)
+        .nullable()
+        .optional()
+        .describe("Replacement agent-visible description."),
+    refreshSpec: z
+        .boolean()
+        .optional()
+        .describe("Re-fetch the source and rebuild the tool catalog. Connections and policy rules survive it."),
+    specOverrides: z
+        .array(AnyObjectSchema)
+        .max(200)
+        .optional()
+        .describe("Replacement RFC 6902 JSON Patch operations. Applied on the next spec build."),
+})
+    .refine((value) => Object.keys(value).length > 0, {
+    message: "At least one mutable connector field is required.",
+});
+export const connectorDetectSchema = z.object({
+    url: z
+        .string()
+        .url()
+        .describe("Any URL a service published. Every plugin's detector gets a look at it."),
+});
+export const ConnectorDetectionSchema = z
+    .object({
+    kind: connectorSourceKindSchema.describe("Source kind this candidate would register as."),
+    confidence: z
+        .enum(["high", "medium", "low"])
+        .describe("How sure the detector is. Ranked highest first."),
+    endpoint: z
+        .string()
+        .url()
+        .describe("The URL to register, which may not be the URL that was pasted."),
+    title: z.string().describe("Name the source calls itself."),
+    slug: z.string().describe("Suggested slug, already checked against the team's connectors."),
+    presetId: z
+        .string()
+        .nullable()
+        .describe("Catalog row this resolved to, when the paste matched a known service."),
+})
+    .describe("One candidate connector behind a pasted URL.");
+export const connectorListQuerySchema = cursorListQuerySchema.extend({
+    query: z
+        .string()
+        .trim()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("Free-text filter over slug, title, and description."),
+    source: connectorSourceKindSchema
+        .optional()
+        .describe("Show only connectors of this source kind."),
+});
+export const connectorToolListQuerySchema = cursorListQuerySchema.extend({
+    query: z
+        .string()
+        .trim()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("Free-text filter over tool name and summary."),
+    effect: policyActionSchema.optional().describe("Show only tools that resolve to this effect."),
+});
+// ---------------------------------------------------------------------------
+// Connect — one call, three possible answers.
+// ---------------------------------------------------------------------------
+export const connectionCredentialSchema = z
+    .discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("api_key"),
+        value: z
+            .string()
+            .min(1)
+            .describe("The key. Write-only: sealed on arrival, never returned by any endpoint."),
+    }),
+    z.object({
+        kind: z.literal("fields"),
+        values: z
+            .record(z.string(), z.string())
+            .describe("Values keyed by the field names the connector asked for. Write-only, same as a key."),
+    }),
+])
+    .describe("A credential going in. Nothing here ever comes back out.");
+// One call to connect anything. The server works out whether it can finish now,
+// needs the user at an authorization page, or needs values it does not have —
+// so no client has to know a provider's auth shape before it starts.
+export const connectionCreateSchema = z.object({
+    connector: z.string().min(1).describe("Connector slug to connect."),
+    owner: connectionOwnerSchema.describe("Share it with the team, or keep it yours within this team."),
+    displayName: z
+        .string()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("What to call it. Defaults to the connector's title."),
+    description: z
+        .string()
+        .max(1_000)
+        .optional()
+        .describe("Agent-visible note on what this connection is for."),
+    authMethod: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Which of the connector's auth methods to use. Required only when more than one could apply."),
+    credential: connectionCredentialSchema
+        .optional()
+        .describe("Omit it and the server tells you what it needs."),
+    scopes: z
+        .array(z.string())
+        .optional()
+        .describe("Narrow the authorization request below the method's defaults."),
+    returnPath: z
+        .string()
+        .startsWith("/", "Give a dashboard path, not an absolute URL.")
+        .max(512)
+        .optional()
+        .describe("Dashboard path to land on after authorization. Same-origin only; absolute URLs are rejected."),
+});
+export const ConnectionCreateResultSchema = z
+    .discriminatedUnion("status", [
+    z.object({
+        status: z.literal("connected").describe("Done. The connection is usable now."),
+        connection: ConnectionSchema,
+    }),
+    z.object({
+        status: z
+            .literal("authorization_required")
+            .describe("Send the user to `authorizeUrl`; the callback completes it."),
+        connection: ConnectionSchema.describe("Already created, in `pending_authorization`, so it has an id to watch."),
+        authorizeUrl: z
+            .string()
+            .url()
+            .describe("Provider authorization page. Open it in a window you reserved beforehand."),
+        expiresAt: z
+            .string()
+            .datetime()
+            .describe("After this the authorization attempt is dead; start over."),
+    }),
+    z.object({
+        status: z
+            .literal("input_required")
+            .describe("Nothing was created. Collect these values and call again."),
+        connector: z.string().describe("Connector slug this applies to."),
+        authMethod: z
+            .string()
+            .describe("Auth method the fields belong to. Send it back on the next call."),
+        fields: z.array(ConnectorFieldSchema).describe("What to ask for, in the order to ask."),
+    }),
+])
+    .describe("The three ways connecting can end. Branch on `status`; there is no fourth.");
+export const connectionCompleteSchema = z.object({
+    state: z
+        .string()
+        .min(1)
+        .describe("Opaque state from the authorization redirect. Addresses the attempt on its own."),
+    code: z.string().min(1).describe("Authorization code from the provider."),
+});
+// Credentials are immutable: to rotate one, reconnect. Editing a live credential
+// in place gives you a connection whose history no longer describes what it did.
+// `isDefault` is not here on purpose: the default is derived (the only live
+// connection on a connector), never a flag a caller sets.
+export const connectionPatchSchema = z
+    .object({
+    serving: z.boolean().optional(),
+    displayName: z.string().min(1).max(255).optional().describe("Replacement label."),
+    description: z
+        .string()
+        .max(1_000)
+        .nullable()
+        .optional()
+        .describe("Replacement agent-visible description."),
+})
+    .refine((value) => Object.keys(value).length > 0, {
+    message: "At least one mutable connection field is required. Credentials are immutable — reconnect instead.",
+});
+export const connectionListQuerySchema = cursorListQuerySchema.extend({
+    owner: connectionOwnerSchema
+        .or(z.literal("any"))
+        .default("any")
+        .describe("Whose connections to list. `any` is everything the calling credential may use."),
+    connector: z.string().min(1).optional().describe("Show only connections of this connector."),
+    status: connectionStatusSchema.optional().describe("Show only connections in this state."),
+    includeRevoked: z.coerce.boolean().default(false).describe("Include disconnected connections."),
+});
+// ---------------------------------------------------------------------------
+// Policy.
+// ---------------------------------------------------------------------------
+export const policyRuleCreateSchema = z.object({
+    pattern: z
+        .string()
+        .min(1)
+        .max(512)
+        .describe("`*`, `<connector>/*`, `<connectionId>/*`, or `<connectionId>/<tool>`."),
+    action: policyActionSchema,
+    owner: connectionOwnerSchema.describe("Team rules apply to everyone and are a floor personal rules cannot loosen."),
+});
+export const policyRulePatchSchema = z.object({
+    action: policyActionSchema.describe("Replacement action. A rule's pattern and owner are fixed — delete and re-add."),
+});
+export const policyResolveQuerySchema = z.object({
+    address: z.string().min(1).max(512).describe("`<connectionId>/<tool>` to resolve."),
+});
+// ---------------------------------------------------------------------------
+// Runs.
+// ---------------------------------------------------------------------------
+export const connectorRunInputSchema = z
+    .discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("tool"),
+        address: z
+            .string()
+            .min(1)
+            .max(512)
+            .describe("`<connectionId>/<tool>`, straight off a tool listing."),
+        args: AnyObjectSchema.default({}).describe("Arguments, validated against the tool's own input schema."),
+    }),
+    z.object({
+        kind: z.literal("code"),
+        code: z
+            .string()
+            .min(1)
+            .max(200_000)
+            .describe("A program run in the sandbox. It may call any tool the calling credential is granted."),
+    }),
+])
+    .describe("One call, or a program that makes many. Same endpoint either way.");
+export const connectorRunCreateSchema = z.object({
+    input: connectorRunInputSchema,
+    waitMs: z
+        .number()
+        .int()
+        .min(0)
+        .max(120_000)
+        .optional()
+        .describe("How long to hold the request waiting for a terminal status before answering `running`."),
+    idempotencyKey: z
+        .string()
+        .min(1)
+        .max(320)
+        .optional()
+        .describe("Retry with the same key to get the original run back (200, not 201) instead of running it twice."),
+    unattendedApprovals: z
+        .enum(["park", "deny"])
+        .default("park")
+        .describe("What to do when a call needs approval and nobody is watching: park it for a person, or fail fast."),
+});
+export const connectorRunResumeSchema = z.object({
+    action: z
+        .enum(["accept", "decline", "cancel"])
+        .optional()
+        .describe("Omit to leave it waiting for a person. A run parked in `human` mode refuses a machine decision."),
+    content: AnyObjectSchema.optional().describe("Values the paused call asked for, when the approval collected any."),
+});
+export const connectorRunListQuerySchema = cursorListQuerySchema.extend({
+    origin: connectorRunOriginSchema.optional(),
+    space: z.string().min(1).optional().describe("Filter by Space id."),
+    status: runStatusSchema.optional().describe("`awaiting_approval` is the approvals inbox query."),
+    connection: z.string().min(1).optional().describe("Show only runs that touched this connection."),
+});
+// ---------------------------------------------------------------------------
+// Params.
+// ---------------------------------------------------------------------------
+export const ConnectorParamsSchema = z.object({
+    connectorRef: z.string().min(1).describe("Connector slug."),
+});
+export const ConnectionParamsSchema = z.object({
+    connectionId: z.string().min(1).describe("Connection id (`cxn_`)."),
+});
+export const PolicyRuleParamsSchema = z.object({
+    policyRuleId: z.string().min(1).describe("Policy rule id."),
+});
+export const ConnectorRunParamsSchema = z.object({
+    runId: z.string().min(1).describe("Run id (`cxr_`)."),
+});
+// ---------------------------------------------------------------------------
+// Responses.
+// ---------------------------------------------------------------------------
+export const connectorCatalogListResponseSchema = z.object({
+    data: z.array(ConnectorCatalogEntrySchema),
+    pagination: CursorPaginationSchema,
+});
+export const connectorListResponseSchema = z.object({
+    data: z.array(ConnectorSchema),
+    pagination: CursorPaginationSchema,
+});
+export const connectorResponseSchema = dataEnvelope(ConnectorSchema);
+export const connectorDetectResponseSchema = dataEnvelope(z.array(ConnectorDetectionSchema));
+export const connectorDeleteResponseSchema = dataEnvelope(z.null().describe("Removing a connector returns no resource body."));
+export const connectionListResponseSchema = z.object({
+    data: z.array(ConnectionSchema),
+    pagination: CursorPaginationSchema,
+});
+export const connectionResponseSchema = dataEnvelope(ConnectionSchema);
+export const connectionCreateResponseSchema = dataEnvelope(ConnectionCreateResultSchema);
+export const connectionHealthResponseSchema = dataEnvelope(ConnectionHealthSchema);
+// Disconnect purges the credential and tombstones the row; provider-side cleanup
+// may outlive the request, so it carries an operation handle.
+export const connectionDisconnectResponseSchema = mutationEnvelope(ConnectionSchema);
+export const connectionRefreshResponseSchema = mutationEnvelope(ConnectionSchema);
+export const connectorToolListResponseSchema = z.object({
+    data: z.array(ToolSchema),
+    pagination: CursorPaginationSchema,
+});
+export const policyRuleListResponseSchema = dataEnvelope(z.array(PolicyRuleSchema));
+export const policyRuleResponseSchema = dataEnvelope(PolicyRuleSchema);
+export const policyRuleDeleteResponseSchema = dataEnvelope(z.null().describe("Removing a policy rule returns no resource body."));
+export const policyResolveResponseSchema = dataEnvelope(PolicyResolutionSchema);
+export const connectorRunResponseSchema = dataEnvelope(ConnectorRunSchema);
+export const connectorRunListResponseSchema = z.object({
+    data: z.array(ConnectorRunSchema),
+    pagination: CursorPaginationSchema,
+});
+export const connectorRoleNameSchema = z
+    .string()
+    .regex(/^[a-z][a-zA-Z0-9]*$/)
+    .max(64);
+export const connectorRoleSchema = z.object({
+    role: connectorRoleNameSchema,
+    as: z.enum(["team", "owner", "visitor"]),
+    connector: z.string().min(1).optional(),
+});
+export const CONNECTOR_CALL_STATE_COPY = {
+    ok: "Connected.",
+    connect_required: "Connect your account to continue.",
+    reconnect_required: "Reconnect your account to continue.",
+    approval_pending: "This action is waiting for approval.",
+    forbidden: "You do not have permission to use this connection.",
+    unbound: "The site owner needs to connect this service.",
+    unavailable: "This service is unavailable. Try again.",
+};
+export const ConnectorCallStateSchema = z.object({
+    role: connectorRoleNameSchema.optional(),
+    code: z.enum([
+        "ok",
+        "connect_required",
+        "reconnect_required",
+        "approval_pending",
+        "forbidden",
+        "unbound",
+        "unavailable",
+    ]),
+    message: z.string(),
+    runId: z.string().optional(),
+    approvalUrl: z.string().optional(),
+    connectUrl: z.string().optional(),
+});
+export class ConnectorCallError extends Error {
+    state;
+    constructor(state) {
+        super(state.message);
+        this.state = state;
+        this.name = "ConnectorCallError";
+    }
+}
+export const spaceConnectorBindingSchema = connectorRoleSchema.extend({
+    connection: ConnectionSchema.nullable(),
+    visitorConnections: z.object({ count: z.number().int().nonnegative() }).optional(),
+    boundByUserId: z.string().nullable(),
+    createdAt: z.string().datetime().nullable(),
+});
+export const listSpaceConnectorBindingsResponseSchema = dataEnvelope(z.object({
+    bindings: z.array(spaceConnectorBindingSchema),
+    access: z.enum(["private", "team", "public"]),
+}));
+export const bindSpaceConnectorRequestSchema = z.object({ connectionId: z.string().min(1) });
+export const spaceConnectorBindingResponseSchema = dataEnvelope(spaceConnectorBindingSchema);
+export const unbindSpaceConnectorResponseSchema = dataEnvelope(z.null());
+const runtimeConnectorArgsSchema = z.record(z.string(), z.json());
+export const runtimeConnectorCallRequestSchema = z.object({
+    role: connectorRoleNameSchema,
+    tool: z.string().min(1).max(512),
+    args: runtimeConnectorArgsSchema,
+    visitor: z
+        .object({
+        subject: z.string().min(1),
+        email: z.string().optional(),
+        emailVerified: z.boolean().optional(),
+    })
+        .nullable()
+        .default(null),
+    handler: z.object({
+        name: z.string().min(1),
+        mode: z.enum(["read", "write"]),
+        callIndex: z.number().int().nonnegative().default(0),
+    }),
+    requestId: z.string().optional(),
+    waitMs: z.number().int().min(0).max(25000).default(25000),
+});
+export const runtimeConnectorCallResponseSchema = z.object({
+    state: ConnectorCallStateSchema,
+    run: ConnectorRunSchema.optional(),
+});
+export const visitorConnectorIdentitySchema = z.object({
+    role: connectorRoleNameSchema,
+    visitorSubject: z
+        .string()
+        .min(1)
+        .max(512)
+        .refine((subject) => !subject.startsWith("guest:")),
+});
+export const visitorConnectionStartSchema = visitorConnectorIdentitySchema.extend({
+    origin: z
+        .url()
+        .refine((value) => new URL(value).protocol === "https:" && new URL(value).origin === value),
+    returnTo: z.string().max(4096).default("/"),
+});
+export const visitorConnectionCompleteSchema = visitorConnectorIdentitySchema.extend({
+    state: z.string().min(1).max(16384),
+    code: z.string().min(1).max(8192),
+});
+export const visitorConnectionStartResponseSchema = dataEnvelope(z.object({ authorizeUrl: z.url() }));
+export const visitorConnectionCompleteResponseSchema = dataEnvelope(z.object({ returnTo: z.string() }));
+export const visitorConnectionUsersResponseSchema = dataEnvelope(z.array(z.object({
+    userRef: z.string(),
+    count: z.number().int().nonnegative(),
+    roles: z.array(connectorRoleNameSchema),
+})));