@treeseed/sdk 0.13.0-rc.11 → 0.13.0-rc.111

package/dist/operator-contracts/catalog/provider-environment-operations.d.ts

@@ -0,0 +1,41 @@
+export declare const PROVIDER_ENVIRONMENT_OPERATIONS: {
+    readonly registrationCode: {
+        readonly status: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+            teamId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly reveal: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+            teamId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly rotate: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+            teamId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+    };
+    readonly environmentProfiles: {
+        readonly list: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+            teamId: string;
+            providerId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly show: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+            teamId: string;
+            providerId: string;
+            profileId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly publish: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+            profileId: string;
+        }, {}, Record<string, unknown>, Record<string, unknown>>;
+    };
+    readonly environmentGrants: {
+        readonly show: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+            teamId: string;
+            assignmentId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly put: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+            teamId: string;
+            assignmentId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly revoke: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+            teamId: string;
+            assignmentId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+    };
+};

package/dist/operator-contracts/catalog/provider-environment-operations.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { defineOperation } from "../operation-builder.js";
+const empty = z.object({}).strict();
+const none = z.undefined();
+const record = z.record(z.unknown());
+function teamOperation(operationId, method, path, pathShape, options = {}) {
+  const kind = method === "GET" ? "read" : "mutation";
+  const riskClass = options.risk ?? "ordinary";
+  return defineOperation({
+    operationId,
+    description: `${kind === "read" ? "Read" : "Apply"} ${operationId}.`,
+    rest: { method, path },
+    parameters: `treeseed.${operationId}.parameters/v1`,
+    capability: options.capability ?? (kind === "read" ? "providers.read" : "providers.write"),
+    authentication: "oauth",
+    oauthScopes: kind === "read" ? ["treeseed:read"] : ["treeseed:admin"],
+    kind,
+    riskClass,
+    confirmation: riskClass === "ordinary" ? "never" : "input_required",
+    surfaces: ["rest", "cli"],
+    cacheScope: kind === "read" ? "principal" : "none",
+    pagination: options.pagination ?? "none",
+    concurrencyRequired: options.concurrency ?? ["DELETE", "PUT"].includes(method),
+    redactedPaths: options.redactedPaths
+  }, { path: z.object(pathShape).strict(), query: kind === "read" ? record : empty, body: kind === "read" ? none : record, output: record });
+}
+const providerPublish = defineOperation({
+  operationId: "providers.environment.profiles.publish",
+  description: "Publish a value-free provider environment profile descriptor.",
+  rest: { method: "PUT", path: "/v1/provider/environment-profiles/{profileId}" },
+  parameters: "treeseed.providers.environment.profiles.publish.parameters/v1",
+  capability: "providers.execute",
+  authentication: "provider",
+  oauthScopes: [],
+  kind: "mutation",
+  riskClass: "ordinary",
+  confirmation: "never",
+  surfaces: ["rest"],
+  cacheScope: "none",
+  pagination: "none"
+}, { path: z.object({ profileId: z.string().min(1) }).strict(), query: empty, body: record, output: record });
+const PROVIDER_ENVIRONMENT_OPERATIONS = {
+  registrationCode: {
+    status: teamOperation("providers.registration.code.status", "GET", "/v1/teams/{teamId}/capacity-provider-registration-code", { teamId: z.string().min(1) }),
+    reveal: teamOperation("providers.registration.code.reveal", "POST", "/v1/teams/{teamId}/capacity-provider-registration-code/reveal", { teamId: z.string().min(1) }, { risk: "credential", redactedPaths: ["output.registrationCode"] }),
+    rotate: teamOperation("providers.registration.code.rotate", "POST", "/v1/teams/{teamId}/capacity-provider-registration-code/rotate", { teamId: z.string().min(1) }, { risk: "credential", redactedPaths: ["output.registrationCode"], concurrency: true })
+  },
+  environmentProfiles: {
+    list: teamOperation("providers.environment.profiles.list", "GET", "/v1/teams/{teamId}/capacity-providers/{providerId}/environment-profiles", { teamId: z.string().min(1), providerId: z.string().min(1) }, { pagination: "cursor" }),
+    show: teamOperation("providers.environment.profiles.show", "GET", "/v1/teams/{teamId}/capacity-providers/{providerId}/environment-profiles/{profileId}", { teamId: z.string().min(1), providerId: z.string().min(1), profileId: z.string().min(1) }),
+    publish: providerPublish
+  },
+  environmentGrants: {
+    show: teamOperation("providers.environment.grants.show", "GET", "/v1/teams/{teamId}/assignments/{assignmentId}/environment-grant", { teamId: z.string().min(1), assignmentId: z.string().min(1) }),
+    put: teamOperation("providers.environment.grants.put", "PUT", "/v1/teams/{teamId}/assignments/{assignmentId}/environment-grant", { teamId: z.string().min(1), assignmentId: z.string().min(1) }, { risk: "authority" }),
+    revoke: teamOperation("providers.environment.grants.revoke", "DELETE", "/v1/teams/{teamId}/assignments/{assignmentId}/environment-grant", { teamId: z.string().min(1), assignmentId: z.string().min(1) }, { risk: "destructive" })
+  }
+};
+export {
+  PROVIDER_ENVIRONMENT_OPERATIONS
+};

package/dist/operator-contracts/catalog/services/identity-commands.d.ts

@@ -0,0 +1,2 @@
+import type { CommandNodeDescriptor } from '../../command-tree.js';
+export declare function identityLoginCommand(value: CommandNodeDescriptor): CommandNodeDescriptor;

package/dist/operator-contracts/catalog/services/identity-commands.js

@@ -0,0 +1,13 @@
+function identityLoginCommand(value) {
+  if (value.nodeType !== "leaf") throw new Error("Authentication login must be a leaf command.");
+  return { ...value, options: [
+    ...value.options ?? [],
+    { name: "--timeout", description: "Maximum seconds to wait for identity authorization.", type: "number" },
+    { name: "--device", description: "Use headless device authorization instead of local browser PKCE.", type: "boolean" },
+    { name: "--issuer", description: "Choose an authorization server advertised by the selected API.", type: "string" },
+    { name: "--scope", description: "Comma-separated additional API scopes to request explicitly, such as treeseed:admin. Does not grant application permissions.", type: "string" }
+  ] };
+}
+export {
+  identityLoginCommand
+};

package/dist/operator-contracts/catalog/services/secret-commands.d.ts

@@ -0,0 +1,2 @@
+import type { CommandNodeDescriptor } from '../../command-tree.js';
+export declare const managedSecretCommands: CommandNodeDescriptor;

package/dist/operator-contracts/catalog/services/secret-commands.js

@@ -0,0 +1,31 @@
+const managedSecretCommands = {
+  nodeType: "branch",
+  segment: "services",
+  description: "Team service credentials.",
+  children: [{
+    nodeType: "branch",
+    segment: "credentials",
+    description: "Manage credentials in core OpenBao.",
+    children: ["show", "put", "delete", "validate"].map((name) => ({
+      nodeType: "leaf",
+      segment: name,
+      description: `${name} an exact service credential profile.`,
+      kind: name === "show" ? "read" : "mutation",
+      arguments: [{ name: "connection", description: "Service connection ID.", required: true }, { name: "profile", description: "Credential profile ID.", required: true }],
+      options: [
+        { name: "--team", description: "Authorized team ID.", type: "string" },
+        ...name === "show" ? [] : [
+          { name: "--plan", description: "Inspect the proposed operation without mutation or secret input.", type: "boolean" },
+          { name: "--expected-version", description: "Exact current credential version; zero for first creation.", type: "number", required: true }
+        ],
+        ...name === "put" ? [{ name: "--stdin", description: "Read the credential field object as JSON from standard input.", type: "boolean" }] : []
+      ],
+      authorization: { capability: name === "show" ? "secrets.read" : "secrets.write", confirmation: "never" },
+      resultSchemaId: `treeseed.services.credentials.${name}/v1`,
+      execution: { kind: "local", handlerId: `local.services.credentials.${name}` }
+    }))
+  }]
+};
+export {
+  managedSecretCommands
+};

package/dist/operator-contracts/catalog/services/secret-operations.d.ts

@@ -0,0 +1,62 @@
+export declare const SECRET_OPERATIONS: {
+    readonly credentialStatus: import("../../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+        profileId: string;
+        connectionId: string;
+    }, {}, {
+        expectedVersion: number;
+    } | undefined, {
+        version: number;
+        teamId: string;
+        profileId: string;
+        connectionId: string;
+        configured: boolean;
+        custody: "openbao";
+        fields: string[];
+    }>;
+    readonly putCredentials: import("../../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+        profileId: string;
+        connectionId: string;
+    }, {}, {
+        expectedVersion: number;
+    } | undefined, {
+        version: number;
+        teamId: string;
+        profileId: string;
+        connectionId: string;
+        configured: boolean;
+        custody: "openbao";
+        fields: string[];
+    }>;
+    readonly deleteCredentials: import("../../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+        profileId: string;
+        connectionId: string;
+    }, {}, {
+        expectedVersion: number;
+    } | undefined, {
+        version: number;
+        teamId: string;
+        profileId: string;
+        connectionId: string;
+        configured: boolean;
+        custody: "openbao";
+        fields: string[];
+    }>;
+    readonly validateCredentials: import("../../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+        profileId: string;
+        connectionId: string;
+    }, {}, {
+        expectedVersion: number;
+    } | undefined, {
+        version: number;
+        teamId: string;
+        profileId: string;
+        connectionId: string;
+        configured: boolean;
+        custody: "openbao";
+        fields: string[];
+    }>;
+};

package/dist/operator-contracts/catalog/services/secret-operations.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { defineOperation } from "../../operation-builder.js";
+const id = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u);
+const path = z.object({ teamId: id, connectionId: id, profileId: id }).strict();
+const version = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER - 1);
+const descriptor = z.object({
+  teamId: id,
+  connectionId: id,
+  profileId: id,
+  custody: z.literal("openbao"),
+  version,
+  configured: z.boolean(),
+  fields: z.array(id)
+}).strict();
+const put = z.object({
+  expectedVersion: version,
+  values: z.record(z.string().max(1024 * 1024)).refine((v) => Object.keys(v).length > 0 && Object.keys(v).length <= 128)
+}).strict();
+function operation(name, method) {
+  const read = method === "GET";
+  return defineOperation({
+    operationId: `services.credentials.${name}`,
+    description: `${name} managed service credentials.`,
+    rest: { method, path: `/v1/teams/{teamId}/services/{connectionId}/credentials/{profileId}${name === "validate" ? "/validate" : ""}` },
+    parameters: `treeseed.services.credentials.${name}.parameters/v1`,
+    capability: read ? "secrets.read" : "secrets.write",
+    authentication: "oauth",
+    oauthScopes: read ? ["treeseed:read"] : ["treeseed:projects:write"],
+    kind: read ? "read" : "mutation",
+    riskClass: read ? "ordinary" : "credential",
+    confirmation: "never",
+    surfaces: ["rest"],
+    cacheScope: "none",
+    pagination: "none",
+    redactedPaths: ["body.values"]
+  }, {
+    path,
+    query: z.object({}).strict(),
+    body: read ? z.undefined() : name === "put" ? put : z.object({ expectedVersion: version }).strict(),
+    output: name === "validate" ? z.object({ ok: z.boolean() }).strict() : descriptor
+  });
+}
+const SECRET_OPERATIONS = {
+  credentialStatus: operation("show", "GET"),
+  putCredentials: operation("put", "PUT"),
+  deleteCredentials: operation("delete", "DELETE"),
+  validateCredentials: operation("validate", "POST")
+};
+export {
+  SECRET_OPERATIONS
+};

package/dist/operator-contracts/catalog/treeai-operations.d.ts

@@ -0,0 +1,13 @@
+import type { ControlPlaneOperationBinding } from '../control-plane-operation.js';
+export declare const TREEAI_OPENAPI_DIGESTS: {
+    readonly inference: "sha256:29255fae4e74aa0fb96d8abd1cdc5d869f469fc9bb55a68060eeae6d86f4273d";
+    readonly training: "sha256:de80f39ca9d0d5a2a7ca6ce588326d3a562c771bc7e077b7e6c4949134ef2143";
+    readonly lab: "sha256:8f9a3ca31a63143506e1b28ddb78eda50b2f6760278531b723047d968f56aa07";
+};
+export declare const TREEAI_CONTROL_PLANE_OPERATION_LIST: readonly ControlPlaneOperationBinding<{
+    nodeId: string;
+}, {}, Record<string, unknown> | undefined, Record<string, unknown>>[];
+export declare const TREEAI_CONTROL_PLANE_OPERATIONS: Readonly<Record<string, ControlPlaneOperationBinding<any, any, any, any>>>;
+export declare function treeAiControlPlaneOperation(upstreamOperationId: string): ControlPlaneOperationBinding<{
+    nodeId: string;
+}, {}, Record<string, unknown> | undefined, Record<string, unknown>>;

package/dist/operator-contracts/catalog/treeai-operations.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { defineOperation } from "../operation-builder.js";
+import { TREEAI_UPSTREAM_OPERATIONS } from "../../treeai/generated/upstream.js";
+const TREEAI_OPENAPI_DIGESTS = {
+  inference: "sha256:29255fae4e74aa0fb96d8abd1cdc5d869f469fc9bb55a68060eeae6d86f4273d",
+  training: "sha256:de80f39ca9d0d5a2a7ca6ce588326d3a562c771bc7e077b7e6c4949134ef2143",
+  lab: "sha256:8f9a3ca31a63143506e1b28ddb78eda50b2f6760278531b723047d968f56aa07"
+};
+function treeSeedOperationId(operation) {
+  return `treeai.${operation.operationId.toLowerCase().replace(/[^a-z0-9]+/gu, ".").replace(/^\.|\.$/gu, "")}`;
+}
+function risk(operation) {
+  if (/rollback|cancel|disable/u.test(operation.operationId)) return "destructive";
+  if (operation.kind === "mutation" && (/promot|enable|activate|campaigns/u.test(operation.operationId) || /(?:^|\.)mode(?:\.|$)/u.test(operation.operationId))) return "authority";
+  return "ordinary";
+}
+function pathShape(path) {
+  return Object.fromEntries([...path.matchAll(/\{([^}]+)\}/gu)].map((match) => [match[1], z.string().min(1)]));
+}
+function binding(operation) {
+  const method = operation.method;
+  const kind = operation.kind;
+  const riskClass = risk(operation);
+  const path = `/v1/ai/nodes/{nodeId}/${operation.service}${operation.path}`;
+  return defineOperation({
+    operationId: treeSeedOperationId(operation),
+    description: `${operation.summary} through a node-scoped TreeAI proxy.`,
+    rest: { method, path },
+    parameters: `treeseed.${treeSeedOperationId(operation)}.parameters/v1`,
+    capability: `treeai.${operation.service}.${kind}`,
+    authentication: "oauth_or_provider",
+    oauthScopes: kind === "read" ? ["treeseed:read"] : ["treeseed:execution"],
+    kind,
+    riskClass,
+    confirmation: riskClass === "ordinary" ? "never" : "input_required",
+    idempotencyRequired: kind === "mutation",
+    surfaces: ["rest", "cli"],
+    cacheScope: kind === "read" ? "principal" : "none",
+    pagination: "none",
+    redactedPaths: ["headers.authorization"],
+    upstream: { service: "treeai", operationId: operation.operationId, contractVersion: "3.1.1", contractDigest: TREEAI_OPENAPI_DIGESTS[operation.service] }
+  }, {
+    path: z.object({ nodeId: z.string().min(1), ...pathShape(operation.path) }).strict(),
+    query: kind === "read" ? z.record(z.unknown()) : z.object({}).strict(),
+    body: kind === "read" ? z.undefined() : z.record(z.unknown()),
+    output: z.record(z.unknown())
+  });
+}
+const TREEAI_CONTROL_PLANE_OPERATION_LIST = Object.freeze(TREEAI_UPSTREAM_OPERATIONS.map(binding));
+const TREEAI_CONTROL_PLANE_OPERATIONS = Object.freeze(Object.fromEntries(TREEAI_CONTROL_PLANE_OPERATION_LIST.map((item) => [item.descriptor.operationId, item])));
+function treeAiControlPlaneOperation(upstreamOperationId) {
+  const operation = TREEAI_CONTROL_PLANE_OPERATION_LIST.find((item) => item.descriptor.upstream?.operationId === upstreamOperationId);
+  if (!operation) throw new Error(`Unknown TreeAI operation ${upstreamOperationId}.`);
+  return operation;
+}
+export {
+  TREEAI_CONTROL_PLANE_OPERATIONS,
+  TREEAI_CONTROL_PLANE_OPERATION_LIST,
+  TREEAI_OPENAPI_DIGESTS,
+  treeAiControlPlaneOperation
+};

package/dist/operator-contracts/command-tree.d.ts

@@ -1,3 +1,4 @@
+import type { ControlPlaneOperationBinding } from './control-plane-operation.js';
 export type CommandOperationKind = 'read' | 'mutation';
 export type CommandExecutionMode = 'execute' | 'plan';
 export type CommandErrorCategory = 'unknown_command' | 'invalid_input' | 'ambiguous_context' | 'authentication_required' | 'authorization_denied' | 'confirmation_required' | 'policy_blocked' | 'stale_preflight' | 'conflict' | 'not_found' | 'provider_unavailable' | 'rate_limited' | 'internal_error';
@@ -19,6 +20,31 @@ export interface CommandAuthorizationDescriptor {
     capability: string;
     confirmation: 'never' | 'destructive' | 'credential' | 'authority' | 'production' | 'irreversible';
 }
+export type CommandInputSource = 'argument' | 'context' | 'option';
+export type CommandInputTarget = 'path' | 'query' | 'body';
+export interface CommandInputBinding {
+    field: string;
+    source: CommandInputSource;
+    name: string;
+    target: CommandInputTarget;
+    required?: boolean;
+    transform?: 'identity' | 'integer' | 'csv';
+}
+export type CommandExecutionBinding = {
+    kind: 'operation';
+    operationId: `${string}.${string}`;
+    input: CommandInputBinding[];
+} | {
+    kind: 'protocol';
+    handlerId: `protocol.${string}`;
+} | {
+    kind: 'local';
+    handlerId: `local.${string}`;
+} | {
+    kind: 'unavailable';
+    code: string;
+    reason: string;
+};
 export interface CommandLeafDescriptor {
     segment: string;
     description: string;
@@ -27,6 +53,7 @@ export interface CommandLeafDescriptor {
     options?: CommandOptionDescriptor[];
     authorization?: CommandAuthorizationDescriptor;
     resultSchemaId: string;
+    execution: CommandExecutionBinding;
 }
 export interface CommandBranchDescriptor {
     segment: string;
@@ -76,4 +103,5 @@ export interface CommandTreeDiagnostic {
     message: string;
 }
 export declare function validateCommandTree(tree: CommandTreeDescriptor): CommandTreeDiagnostic[];
+export declare function validateCommandOperationBindings(tree: CommandTreeDescriptor, operations: readonly ControlPlaneOperationBinding<any, any, any, any>[]): CommandTreeDiagnostic[];
 export declare function createCommandResult<TResult>(input: Omit<CommandResultEnvelope<TResult>, 'schemaVersion'>): CommandResultEnvelope<TResult>;

package/dist/operator-contracts/command-tree.js

@@ -1,3 +1,4 @@
+import { ZodUndefined } from "zod";
 const SEGMENT = /^[a-z][a-z0-9]*$/;
 const FORBIDDEN_AGENT_MANAGEMENT_OPTIONS = /* @__PURE__ */ new Set([
   "--commit",
@@ -31,6 +32,17 @@ function validateCommandTree(tree) {
       }
       if ("children" in raw) diagnostics.push({ code: "command_node_ambiguous", path: diagnosticPath, message: "Leaf command nodes cannot contain child commands." });
       if (!node.resultSchemaId.trim()) diagnostics.push({ code: "result_schema_required", path: `${diagnosticPath}.resultSchemaId`, message: "Leaf commands require a stable result schema." });
+      if (!node.execution) diagnostics.push({ code: "command_execution_required", path: `${diagnosticPath}.execution`, message: "Every leaf must declare one authoritative execution binding." });
+      if (node.execution?.kind === "operation") {
+        const targets = /* @__PURE__ */ new Set();
+        for (const binding of node.execution.input) {
+          const key = `${binding.target}.${binding.field}`;
+          if (targets.has(key)) diagnostics.push({ code: "command_input_target_duplicate", path: `${diagnosticPath}.execution.input`, message: `Duplicate command input target ${key}.` });
+          targets.add(key);
+          if (!binding.field.trim() || !binding.name.trim()) diagnostics.push({ code: "command_input_binding_invalid", path: `${diagnosticPath}.execution.input`, message: "Command input bindings require field and source names." });
+        }
+      }
+      if (node.execution?.kind === "unavailable" && (!node.execution.code.trim() || !node.execution.reason.trim())) diagnostics.push({ code: "command_unavailable_reason_required", path: `${diagnosticPath}.execution`, message: "Unavailable commands require a stable code and explanation." });
       const optionNames = /* @__PURE__ */ new Set();
       for (const option of node.options ?? []) {
         if (optionNames.has(option.name)) diagnostics.push({ code: "command_option_duplicate", path: `${diagnosticPath}.options.${index}`, message: `Duplicate option ${option.name}.` });
@@ -44,10 +56,47 @@ function validateCommandTree(tree) {
   visit(tree.commands, []);
   return diagnostics;
 }
+function validateCommandOperationBindings(tree, operations) {
+  const diagnostics = [];
+  const catalog = new Map(operations.map((operation) => [operation.descriptor.operationId, operation]));
+  const visit = (nodes, parent) => {
+    for (const node of nodes) {
+      const path = [...parent, node.segment];
+      if (node.nodeType === "branch") {
+        visit(node.children, path);
+        continue;
+      }
+      if (node.execution.kind !== "operation") continue;
+      const binding = catalog.get(node.execution.operationId);
+      const diagnosticPath = `commands.${path.join(".")}.execution`;
+      if (!binding) {
+        diagnostics.push({ code: "command_operation_unknown", path: diagnosticPath, message: `Unknown control-plane operation ${node.execution.operationId}.` });
+        continue;
+      }
+      if (!binding.descriptor.surfaces.includes("cli")) diagnostics.push({ code: "command_operation_surface_missing", path: diagnosticPath, message: `Operation ${node.execution.operationId} does not declare the CLI surface.` });
+      if (binding.descriptor.kind !== node.kind) diagnostics.push({ code: "command_operation_kind_mismatch", path: diagnosticPath, message: `Command and operation ${node.execution.operationId} disagree about mutation behavior.` });
+      const expectedConfirmation = binding.descriptor.confirmation === "input_required" ? binding.descriptor.riskClass : "never";
+      if ((node.authorization?.confirmation ?? "never") !== expectedConfirmation) diagnostics.push({ code: "command_operation_confirmation_mismatch", path: diagnosticPath, message: `Command and operation ${node.execution.operationId} disagree about confirmation.` });
+      const shapes = {
+        path: "shape" in binding.schema.path ? Object.keys(binding.schema.path.shape) : null,
+        query: "shape" in binding.schema.query ? Object.keys(binding.schema.query.shape) : null,
+        body: "shape" in binding.schema.body ? Object.keys(binding.schema.body.shape) : null
+      };
+      for (const input of node.execution.input) {
+        const keys = shapes[input.target];
+        const undefinedSchema = binding.schema[input.target] instanceof ZodUndefined;
+        if (keys !== null && !keys.includes(input.field) || undefinedSchema) diagnostics.push({ code: "command_operation_input_unknown", path: `${diagnosticPath}.input.${input.target}.${input.field}`, message: `Operation ${node.execution.operationId} does not accept ${input.target} field ${input.field}.` });
+      }
+    }
+  };
+  visit(tree.commands, []);
+  return diagnostics.sort((left, right) => `${left.path}:${left.code}`.localeCompare(`${right.path}:${right.code}`));
+}
 function createCommandResult(input) {
   return { schemaVersion: "treeseed.command-result/v1", ...input };
 }
 export {
   createCommandResult,
+  validateCommandOperationBindings,
   validateCommandTree
 };

package/dist/operator-contracts/communication/addressing.d.ts

@@ -0,0 +1,8 @@
+export type CommunicationAddressRequirement = 'required' | 'optional';
+export interface CommunicationAddress {
+    projectSlug: string | null;
+    agentSlug: string;
+    requirement: CommunicationAddressRequirement;
+    address: string;
+}
+export declare function parseCommunicationAddresses(markdown: string): CommunicationAddress[];

package/dist/operator-contracts/communication/addressing.js

@@ -0,0 +1,57 @@
+const ADDRESS = /(^|[^\p{L}\p{N}._%+-])@([a-z0-9][a-z0-9-]*)(?:\/([a-z0-9][a-z0-9-]*))?/giu;
+function visibleMarkdown(markdown) {
+  const lines = markdown.replace(/\r\n?/gu, "\n").split("\n");
+  let fenced = false;
+  return lines.map((line) => {
+    if (/^\s*```/u.test(line)) {
+      fenced = !fenced;
+      return "";
+    }
+    if (fenced || /^\s*>/u.test(line)) return "";
+    return line.replace(/`[^`]*`/gu, "").replace(/!?\[[^\]]*\]\([^)]*\)/gu, "").replace(/\b[\w.+-]+@[\w.-]+\.[a-z]{2,}\b/giu, "");
+  }).join("\n");
+}
+function initialAddressLines(markdown) {
+  const lines = visibleMarkdown(markdown).split("\n");
+  let started = false;
+  const requiredThrough = /* @__PURE__ */ new Map();
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index];
+    const line = source.trim();
+    if (!line && !started) continue;
+    if (!line) break;
+    started = true;
+    const leading = source.match(/^\s*(?:@[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)?[\s,;:—–-]*)+/iu);
+    if (!leading) break;
+    requiredThrough.set(index, leading[0].length);
+    if (source.slice(leading[0].length).trim()) break;
+  }
+  return { markdown: visibleMarkdown(markdown), requiredThrough };
+}
+function parseCommunicationAddresses(markdown) {
+  const visible = initialAddressLines(markdown);
+  const addresses = /* @__PURE__ */ new Map();
+  for (const [lineIndex, line] of visible.markdown.split("\n").entries()) {
+    ADDRESS.lastIndex = 0;
+    for (const match of line.matchAll(ADDRESS)) {
+      const first = match[2].toLowerCase();
+      const second = match[3]?.toLowerCase() ?? null;
+      const projectSlug = second ? first : null;
+      const agentSlug = second ?? first;
+      const key = `${projectSlug ?? ""}/${agentSlug}`;
+      const addressIndex = (match.index ?? 0) + match[1].length;
+      const requirement = addressIndex < (visible.requiredThrough.get(lineIndex) ?? 0) ? "required" : "optional";
+      const existing = addresses.get(key);
+      if (!existing || requirement === "required") addresses.set(key, {
+        projectSlug,
+        agentSlug,
+        requirement,
+        address: `@${projectSlug ? `${projectSlug}/` : ""}${agentSlug}`
+      });
+    }
+  }
+  return [...addresses.values()];
+}
+export {
+  parseCommunicationAddresses
+};