@opengeni/contracts 0.50.0 → 1.0.0

package/src/governed-learning-activation.ts

@@ -0,0 +1,191 @@
+import { z } from "zod";
+
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/);
+const boundedActor = z.string().trim().min(1).max(1_024);
+
+export const GovernedLearningActivationDestination = z.enum(["instruction_policy", "preference"]);
+export const GovernedLearningActivationAuthorityKind = z.enum(["automatic", "human_confirmed"]);
+export type GovernedLearningActivationAuthorityKind = z.infer<
+  typeof GovernedLearningActivationAuthorityKind
+>;
+export type GovernedLearningActivationDestination = z.infer<
+  typeof GovernedLearningActivationDestination
+>;
+
+export const GovernedLearningActivationCaller = z
+  .object({
+    workspaceId: z.string().uuid(),
+    subjectId: boundedActor,
+  })
+  .strict();
+export type GovernedLearningActivationCaller = z.infer<typeof GovernedLearningActivationCaller>;
+
+export const ActivateGovernedLearningDecisionRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    decisionReceiptId: z.string().uuid(),
+  })
+  .strict();
+export type ActivateGovernedLearningDecisionRequest = z.infer<
+  typeof ActivateGovernedLearningDecisionRequest
+>;
+
+export const UndoGovernedLearningActivationRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    activationReceiptId: z.string().uuid(),
+  })
+  .strict();
+export type UndoGovernedLearningActivationRequest = z.infer<
+  typeof UndoGovernedLearningActivationRequest
+>;
+
+const destinationBoundary = {
+  destination: GovernedLearningActivationDestination,
+  destinationProposalId: z.string().uuid(),
+  destinationRevisionId: z.string().uuid(),
+  destinationOldRevisionId: z.string().uuid().nullable(),
+  destinationOldContentHash: sha256.nullable(),
+  destinationOldVersion: z.number().int().nonnegative(),
+  destinationNewContentHash: sha256,
+  destinationNewVersion: z.number().int().positive(),
+  destinationEventId: z.string().uuid(),
+};
+
+/**
+ * Immutable content-free proof that one final automatic evaluator receipt was
+ * revalidated and applied through the destination-owned lifecycle.
+ */
+export const GovernedLearningActivationReceipt = z
+  .object({
+    id: z.string().uuid(),
+    operationId: z.string().uuid(),
+    inputHash: sha256,
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    decisionReceiptId: z.string().uuid(),
+    initiatingHumanSubjectId: boundedActor,
+    serviceActorSubjectId: boundedActor,
+    policyRevisionId: z.string().uuid(),
+    policyHash: sha256,
+    policyActivationVersion: z.number().int().positive(),
+    sourceKind: z.enum(["scoped-knowledge-evidence", "task-note"]),
+    sourceId: z.string().uuid(),
+    sourceAuthorityHash: sha256,
+    proposalId: z.string().uuid(),
+    claimId: z.string().uuid(),
+    evidenceId: z.string().uuid(),
+    knowledgePreviousReviewId: z.string().uuid(),
+    knowledgePreviousReviewRevision: z.number().int().positive(),
+    knowledgeApprovalReviewId: z.string().uuid(),
+    knowledgeApprovalReviewRevision: z.number().int().positive(),
+    knowledgeApprovalInputHash: sha256,
+    ...destinationBoundary,
+    outcome: z.literal("activated"),
+    effectiveAt: z.string().datetime(),
+    /**
+     * `automatic`: a final eligible evaluator receipt under an automatic policy.
+     * `human_confirmed`: the exact initiating human answered the bound
+     * `remember:<proposalId>` structured human-input question with `save`.
+     */
+    authorityKind: GovernedLearningActivationAuthorityKind,
+    humanInputRequestId: z.string().uuid().nullable(),
+    rollback: z
+      .object({
+        supported: z.literal(true),
+        mechanism: z.literal("exact_head_and_latest_review"),
+      })
+      .strict(),
+    createdAt: z.string().datetime(),
+  })
+  .strict();
+export type GovernedLearningActivationReceipt = z.infer<typeof GovernedLearningActivationReceipt>;
+
+export const ActivateHumanConfirmedLearningDecisionRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    decisionReceiptId: z.string().uuid(),
+    humanInputRequestId: z.string().uuid(),
+  })
+  .strict();
+export type ActivateHumanConfirmedLearningDecisionRequest = z.infer<
+  typeof ActivateHumanConfirmedLearningDecisionRequest
+>;
+
+/** Append-only compensation proof. Undo never deletes prior evidence. */
+export const GovernedLearningActivationUndoReceipt = z
+  .object({
+    id: z.string().uuid(),
+    operationId: z.string().uuid(),
+    inputHash: sha256,
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    activationReceiptId: z.string().uuid(),
+    initiatingHumanSubjectId: boundedActor,
+    serviceActorSubjectId: boundedActor,
+    destination: GovernedLearningActivationDestination,
+    knowledgeApprovalReviewId: z.string().uuid(),
+    knowledgeRevocationReviewId: z.string().uuid(),
+    knowledgeRevocationReviewRevision: z.number().int().positive(),
+    knowledgeRevocationInputHash: sha256,
+    destinationActivatedRevisionId: z.string().uuid(),
+    destinationRestoredRevisionId: z.string().uuid().nullable(),
+    destinationActivatedContentHash: sha256,
+    destinationRestoredContentHash: sha256.nullable(),
+    destinationOldVersion: z.number().int().positive(),
+    destinationNewVersion: z.number().int().positive(),
+    destinationEventId: z.string().uuid(),
+    outcome: z.literal("undone"),
+    superseded: z.literal(false),
+    effectiveAt: z.string().datetime(),
+    createdAt: z.string().datetime(),
+  })
+  .strict();
+export type GovernedLearningActivationUndoReceipt = z.infer<
+  typeof GovernedLearningActivationUndoReceipt
+>;
+
+/**
+ * Immutable content-free proof that the exact initiating human confirmed a
+ * user-directed Knowledge claim (`remember` with lane `knowledge`) through the
+ * bound structured human-input question, after which the claim's latest
+ * `proposed` review was superseded by an `approved` service review.
+ */
+export const RememberKnowledgeConfirmationReceipt = z
+  .object({
+    id: z.string().uuid(),
+    operationId: z.string().uuid(),
+    inputHash: sha256,
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+    initiatingHumanSubjectId: boundedActor,
+    serviceActorSubjectId: boundedActor,
+    claimId: z.string().uuid(),
+    evidenceId: z.string().uuid(),
+    taskNoteId: z.string().uuid(),
+    taskNoteTextHash: sha256,
+    humanInputRequestId: z.string().uuid(),
+    previousReviewId: z.string().uuid(),
+    previousReviewRevision: z.number().int().positive(),
+    approvalReviewId: z.string().uuid(),
+    approvalReviewRevision: z.number().int().positive(),
+    createdAt: z.string().datetime(),
+  })
+  .strict();
+export type RememberKnowledgeConfirmationReceipt = z.infer<
+  typeof RememberKnowledgeConfirmationReceipt
+>;
+
+export const ConfirmRememberKnowledgeClaimRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    claimId: z.string().uuid(),
+    humanInputRequestId: z.string().uuid(),
+  })
+  .strict();
+export type ConfirmRememberKnowledgeClaimRequest = z.infer<
+  typeof ConfirmRememberKnowledgeClaimRequest
+>;

package/src/governed-learning-evaluator.ts

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import { WorkspaceLearningMode } from "./workspace-learning-policy";
+
+/**
+ * Automatic is intentionally conservative in the first evaluator tranche.
+ * This constant is platform-owned rather than caller-selectable so an agent or
+ * connector cannot lower the admission floor inside one request.
+ */
+export const GOVERNED_LEARNING_AUTOMATIC_CONFIDENCE_FLOOR_BPS = 8_500;
+export const GOVERNED_LEARNING_MAX_CONFLICT_COUNT = 1_000;
+
+export const GovernedLearningDecisionOutcome = z.enum([
+  "off",
+  "suggest",
+  "automatic",
+  "confidence",
+  "conflict",
+  "stale",
+  "revoked",
+]);
+export type GovernedLearningDecisionOutcome = z.infer<typeof GovernedLearningDecisionOutcome>;
+
+/** Stable order used by TypeScript, SQL constraints, and public receipts. */
+export const GOVERNED_LEARNING_REASON_ORDER = [
+  "policy_off",
+  "evidence_revoked",
+  "proposal_stale",
+  "evidence_conflict",
+  "confidence_below_floor",
+  "policy_suggest",
+  "policy_automatic",
+] as const;
+
+export const GovernedLearningDecisionReason = z.enum(GOVERNED_LEARNING_REASON_ORDER);
+export type GovernedLearningDecisionReason = z.infer<typeof GovernedLearningDecisionReason>;
+
+export const GovernedLearningDecisionFacts = z
+  .object({
+    effectiveMode: WorkspaceLearningMode,
+    confidenceBps: z.number().int().min(0).max(10_000),
+    conflictCount: z.number().int().min(0).max(GOVERNED_LEARNING_MAX_CONFLICT_COUNT),
+    stale: z.boolean(),
+    revoked: z.boolean(),
+  })
+  .strict();
+export type GovernedLearningDecisionFacts = z.infer<typeof GovernedLearningDecisionFacts>;
+
+export const GovernedLearningDecision = z
+  .object({
+    outcome: GovernedLearningDecisionOutcome,
+    reasons: z
+      .array(GovernedLearningDecisionReason)
+      .min(1)
+      .max(GOVERNED_LEARNING_REASON_ORDER.length),
+    automaticEligible: z.boolean(),
+    confidenceFloorBps: z.literal(GOVERNED_LEARNING_AUTOMATIC_CONFIDENCE_FLOOR_BPS),
+  })
+  .strict()
+  .superRefine((decision, context) => {
+    if (decision.automaticEligible !== (decision.outcome === "automatic")) {
+      context.addIssue({
+        code: "custom",
+        path: ["automaticEligible"],
+        message: "automatic eligibility must exactly match the automatic outcome",
+      });
+    }
+    const indexes = decision.reasons.map((reason) =>
+      GOVERNED_LEARNING_REASON_ORDER.indexOf(reason),
+    );
+    if (indexes.some((value, index) => index > 0 && value <= indexes[index - 1]!)) {
+      context.addIssue({
+        code: "custom",
+        path: ["reasons"],
+        message: "governed-learning reasons must be unique and in canonical order",
+      });
+    }
+  });
+export type GovernedLearningDecision = z.infer<typeof GovernedLearningDecision>;
+
+export const GovernedLearningEvaluationAttempt = z
+  .object({
+    workspaceId: z.string().uuid(),
+    subjectId: z.string().trim().min(1).max(1_024),
+    sessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    attemptId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+  })
+  .strict();
+export type GovernedLearningEvaluationAttempt = z.infer<typeof GovernedLearningEvaluationAttempt>;
+
+export const EvaluateGovernedLearningProposalRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    policySnapshotId: z.string().uuid(),
+    proposalId: z.string().uuid(),
+    claimId: z.string().uuid(),
+    evidenceId: z.string().uuid(),
+  })
+  .strict();
+export type EvaluateGovernedLearningProposalRequest = z.infer<
+  typeof EvaluateGovernedLearningProposalRequest
+>;
+
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/);
+
+/**
+ * Content-free immutable evidence. Hashes and bounded enums identify exactly
+ * what was evaluated without copying proposal, fact, citation, or note text.
+ */
+export const GovernedLearningDecisionReceipt = z
+  .object({
+    id: z.string().uuid(),
+    operationId: z.string().uuid(),
+    inputHash: sha256,
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    attemptId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+    initiatingHumanSubjectId: z.string().min(1).max(1_024),
+    policySnapshotId: z.string().uuid(),
+    policySnapshotHash: sha256,
+    policyRevisionId: z.string().uuid().nullable(),
+    policyActivationVersion: z.number().int().nonnegative(),
+    sourceKind: z.enum(["scoped-knowledge-evidence", "task-note"]),
+    sourceId: z.string().uuid(),
+    proposalId: z.string().uuid(),
+    proposalInputHash: sha256,
+    proposalContentHash: sha256,
+    claimId: z.string().uuid(),
+    claimInputHash: sha256,
+    evidenceId: z.string().uuid(),
+    evidenceInputHash: sha256,
+    evidenceContentHash: sha256,
+    evidenceAuthorityHash: sha256,
+    reviewRevision: z.number().int().positive(),
+    reviewState: z.enum(["proposed", "approved", "rejected", "revoked"]),
+    effectiveMode: WorkspaceLearningMode,
+    confidenceBps: z.number().int().min(0).max(10_000),
+    conflictCount: z.number().int().min(0).max(GOVERNED_LEARNING_MAX_CONFLICT_COUNT),
+    outcome: GovernedLearningDecisionOutcome,
+    reasons: z
+      .array(GovernedLearningDecisionReason)
+      .min(1)
+      .max(GOVERNED_LEARNING_REASON_ORDER.length),
+    automaticEligible: z.boolean(),
+    confidenceFloorBps: z.literal(GOVERNED_LEARNING_AUTOMATIC_CONFIDENCE_FLOOR_BPS),
+    createdAt: z.string().datetime(),
+  })
+  .strict()
+  .superRefine((receipt, context) => {
+    const decision = GovernedLearningDecision.safeParse({
+      outcome: receipt.outcome,
+      reasons: receipt.reasons,
+      automaticEligible: receipt.automaticEligible,
+      confidenceFloorBps: receipt.confidenceFloorBps,
+    });
+    if (!decision.success) {
+      for (const issue of decision.error.issues) {
+        context.addIssue({ ...issue, path: issue.path });
+      }
+    }
+    if (
+      receipt.sourceKind === "scoped-knowledge-evidence" &&
+      receipt.sourceId !== receipt.evidenceId
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["sourceId"],
+        message: "scoped-Knowledge evaluation must use its exact evidence id as the source id",
+      });
+    }
+  });
+export type GovernedLearningDecisionReceipt = z.infer<typeof GovernedLearningDecisionReceipt>;

package/src/host-mcp-bindings.ts

@@ -0,0 +1,298 @@
+import { z } from "zod";
+export { HostMcpCreateSelections, type HostMcpCreateSelection } from "./index";
+import {
+  McpServerConnectionRef,
+  SessionTenancyVisibility,
+  ManagedUserResourceGrantMode,
+  stableJson,
+} from "./index";
+import { ConnectionUseAuthoritySnapshot } from "./connection-authority";
+import { ExternalIdentity } from "./external-identities";
+export const HostMcpOwnerSubject = z.union([
+  ExternalIdentity.shape.subjectId,
+  z
+    .string()
+    .max(4096)
+    .regex(/^user:[^\r\n\u0000]+$/),
+]);
+
+/** Credential-free, immutable destination and host connection selection. */
+export const HostMcpBindingDefinition = z
+  .object({
+    serverId: z.string().min(1).max(256),
+    destinationUrl: z
+      .string()
+      .url()
+      .max(4096)
+      .refine((value) => {
+        const url = new URL(value);
+        return url.protocol === "https:" && !url.username && !url.password && !url.hash;
+      }, "Host binding requires an HTTPS destination without userinfo or fragment")
+      .transform((value) => new URL(value).toString()),
+    connectionRef: McpServerConnectionRef,
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.connectionRef.hostBinding)
+      context.addIssue({
+        code: "custom",
+        path: ["connectionRef", "hostBinding"],
+        message: "A binding definition cannot reference another binding",
+      });
+    if (value.connectionRef.authoritySource !== "host" || !value.connectionRef.connectionId)
+      context.addIssue({
+        code: "custom",
+        path: ["connectionRef"],
+        message: "Explicit host connection authority is required",
+      });
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > 65_536)
+      context.addIssue({ code: "custom", message: "Host binding definition exceeds 64 KiB" });
+  });
+export type HostMcpBindingDefinition = z.infer<typeof HostMcpBindingDefinition>;
+
+/** Configuration ceiling, never execution authority. The complete destination
+ * and provider/scope/resource selection stay exact; only the account identifier
+ * is chosen by a captured owner grant in explicit accepted-turn mode. */
+export type HostMcpBindingSelection = {
+  serverId: string;
+  destinationUrl: string;
+  connectionRef: McpServerConnectionRef;
+};
+
+export function hostMcpBindingMatchesSelection(
+  binding: { id: string; generation: number; definition: HostMcpBindingDefinition },
+  selection: HostMcpBindingSelection,
+): boolean {
+  const parsed = McpServerConnectionRef.safeParse(selection.connectionRef);
+  if (!parsed.success || !parsed.data.hostBinding) return false;
+  const { hostBinding, ...configuredRef } = parsed.data;
+  const definition = HostMcpBindingDefinition.safeParse(binding.definition);
+  if (!definition.success) return false;
+  let destinationUrl: string;
+  try {
+    destinationUrl = new URL(selection.destinationUrl).toString();
+  } catch {
+    return false;
+  }
+  if (
+    selection.serverId !== definition.data.serverId ||
+    destinationUrl !== definition.data.destinationUrl
+  )
+    return false;
+  if ("selection" in hostBinding) {
+    const { connectionId: _connectionId, ...selectedRef } = definition.data.connectionRef;
+    return stableJson(configuredRef) === stableJson(selectedRef);
+  }
+  return (
+    binding.id === hostBinding.bindingId &&
+    binding.generation === hostBinding.generation &&
+    stableJson(configuredRef) === stableJson(definition.data.connectionRef)
+  );
+}
+
+export const HostMcpBinding = z
+  .object({
+    id: z.string().uuid(),
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    ownerSubjectId: HostMcpOwnerSubject,
+    authorizationRevision: z.number().int().positive().safe(),
+    generation: z.number().int().positive().safe(),
+    status: z.enum(["active", "revoked"]),
+    definition: HostMcpBindingDefinition,
+    createdAt: z.string().datetime({ offset: true }),
+    revokedAt: z.string().datetime({ offset: true }).nullable(),
+  })
+  .strict();
+export type HostMcpBinding = z.infer<typeof HostMcpBinding>;
+
+export const CreateHostMcpBindingRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    definition: HostMcpBindingDefinition,
+  })
+  .strict();
+export type CreateHostMcpBindingRequest = z.infer<typeof CreateHostMcpBindingRequest>;
+
+const HostMcpGrantRequest = z
+  .object({
+    scope: z.literal("user"),
+    mode: ManagedUserResourceGrantMode,
+    context: SessionTenancyVisibility,
+    sessionId: z.string().uuid().nullable().optional(),
+    expectedAuthorityEpoch: z.number().int().positive().nullable().optional(),
+    workspaceSharedAcknowledged: z.boolean().default(false),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.context === "workspace_shared" && !value.workspaceSharedAcknowledged) {
+      context.addIssue({
+        code: "custom",
+        path: ["workspaceSharedAcknowledged"],
+        message: "workspace_shared requires durable shared-output acknowledgement",
+      });
+    }
+    if (value.mode === "always" && (value.sessionId || value.expectedAuthorityEpoch)) {
+      context.addIssue({ code: "custom", path: ["sessionId"], message: "always is unbound" });
+    }
+    if (value.mode === "session" && (!value.sessionId || !value.expectedAuthorityEpoch)) {
+      context.addIssue({
+        code: "custom",
+        path: ["sessionId"],
+        message: "session requires a target session and expectedAuthorityEpoch",
+      });
+    }
+  });
+
+/** Internal owner-authorized issuance; never itself proves caller identity. */
+const HostMcpDelegationGrant = HostMcpGrantRequest.superRefine((value, context) => {
+  if (
+    Boolean(value.sessionId) !== (value.expectedAuthorityEpoch != null) ||
+    (value.expectedAuthorityEpoch != null && !Number.isSafeInteger(value.expectedAuthorityEpoch))
+  ) {
+    context.addIssue({
+      code: "custom",
+      message: "Host session grants require a matching safe authority epoch",
+    });
+  }
+});
+export const IssueHostMcpDelegationRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    bindingId: z.string().uuid(),
+    expectedBindingGeneration: z.number().int().positive().safe(),
+    grant: HostMcpDelegationGrant,
+  })
+  .strict();
+export type IssueHostMcpDelegationRequest = z.infer<typeof IssueHostMcpDelegationRequest>;
+
+export const HostMcpDelegation = z
+  .object({
+    id: z.string().uuid(),
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    ownerSubjectId: HostMcpOwnerSubject,
+    ownerAuthorizationRevision: z.number().int().positive().safe(),
+    bindingId: z.string().uuid(),
+    bindingGeneration: z.number().int().positive().safe(),
+    grant: HostMcpDelegationGrant,
+    generation: z.number().int().positive().safe(),
+    status: z.enum(["active", "revoked"]),
+    createdAt: z.string().datetime({ offset: true }),
+    revokedAt: z.string().datetime({ offset: true }).nullable(),
+  })
+  .strict();
+export type HostMcpDelegation = z.infer<typeof HostMcpDelegation>;
+
+/** Internal admission evidence, not a caller-supplied permission or credential.
+ * Persistence must construct this from live authenticated authority and freeze
+ * it with accepted work. Runtime use must independently revalidate that work,
+ * membership, binding and delegation. No API key is retained as execution rights.
+ */
+export const HostMcpAcceptedAuthority = z
+  .object({
+    version: z.literal(1),
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    targetSessionId: z.string().uuid(),
+    targetSessionVisibility: SessionTenancyVisibility,
+    targetSessionAuthorityEpoch: z.number().int().positive().safe(),
+    acceptedWork: ConnectionUseAuthoritySnapshot.shape.acceptedWork,
+    bindingId: z.string().uuid(),
+    bindingGeneration: z.number().int().positive().safe(),
+    definition: HostMcpBindingDefinition,
+    ownerSubjectId: HostMcpOwnerSubject,
+    ownerOrganizationMembershipId: z.string().uuid(),
+    ownerMembershipAuthorizationRevision: z.number().int().positive().safe(),
+    delegationId: z.string().uuid(),
+    delegationGeneration: z.number().int().positive().safe(),
+    scheduledOrigin: z
+      .object({
+        taskId: z.string().uuid(),
+        taskAuthorityRevision: z.number().int().positive().safe(),
+        runId: z.string().uuid(),
+      })
+      .strict()
+      .optional(),
+    source: z.discriminatedUnion("kind", [
+      z.object({ kind: z.literal("direct") }).strict(),
+      z.object({ kind: z.literal("scheduled_task") }).strict(),
+      z
+        .object({
+          kind: z.literal("child_turn"),
+          sessionId: z.string().uuid(),
+          turnId: z.string().uuid(),
+        })
+        .strict(),
+      z
+        .object({
+          kind: z.literal("inherited_turn"),
+          sessionId: z.string().uuid(),
+          turnId: z.string().uuid(),
+        })
+        .strict(),
+    ]),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (
+      (value.source.kind === "direct" && value.scheduledOrigin) ||
+      (value.source.kind === "scheduled_task" &&
+        (!value.scheduledOrigin ||
+          value.acceptedWork.kind !== "scheduled_task" ||
+          value.scheduledOrigin.taskId !== value.acceptedWork.taskId ||
+          value.scheduledOrigin.runId !== value.acceptedWork.runId ||
+          value.scheduledOrigin.taskAuthorityRevision !== value.acceptedWork.taskAuthorityRevision))
+    )
+      context.addIssue({
+        code: "custom",
+        message: "Scheduled host authority must retain its exact run origin",
+      });
+    if (
+      value.acceptedWork.kind === "turn" &&
+      value.source.kind === "inherited_turn" &&
+      value.acceptedWork.turnId === value.source.turnId
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["source"],
+        message: "Accepted work cannot inherit from itself",
+      });
+    }
+    if (
+      value.acceptedWork.kind === "scheduled_task" &&
+      !Number.isSafeInteger(value.acceptedWork.taskAuthorityRevision)
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["acceptedWork"],
+        message: "Task authority revision must be a safe integer",
+      });
+    }
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > 65_536) {
+      context.addIssue({ code: "custom", message: "Host accepted authority exceeds 64 KiB" });
+    }
+  });
+export type HostMcpAcceptedAuthority = z.infer<typeof HostMcpAcceptedAuthority>;
+
+/** Credential-free selection frozen on one immutable scheduled-task revision. */
+export const HostMcpTaskAuthority = z
+  .object({
+    version: z.literal(1),
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    taskId: z.string().uuid(),
+    taskAuthorityRevision: z.number().int().positive().safe(),
+    taskExecutionDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    ownerSubjectId: HostMcpOwnerSubject,
+    ownerOrganizationMembershipId: z.string().uuid(),
+    ownerMembershipAuthorizationRevision: z.number().int().positive().safe(),
+    bindingId: z.string().uuid(),
+    bindingGeneration: z.number().int().positive().safe(),
+    delegationId: z.string().uuid(),
+    delegationGeneration: z.number().int().positive().safe(),
+    definition: HostMcpBindingDefinition,
+    context: SessionTenancyVisibility,
+  })
+  .strict();
+export type HostMcpTaskAuthority = z.infer<typeof HostMcpTaskAuthority>;

package/src/image-generation.ts

@@ -16,7 +16,10 @@ const WorkspaceImagePathSchema = z
   // without sending unsupported regex syntax to model providers.
   .refine((path) => path.split("/").every((segment) => segment !== "." && segment !== ".."), {
     message: "Sandbox image paths cannot contain dot segments",
-  });
+  })
+  .describe(
+    "Absolute /workspace path to a PNG, JPEG, or WebP image. Convert SVG or other formats before using them as image-generation references.",
+  );
 
 /** One ordered, workspace-owned input used to guide or edit an image. */
 export const ImageGenerationReferenceSchema = z.discriminatedUnion("kind", [
@@ -49,7 +52,10 @@ export const GenerateImageToolInput = z
       .array(ImageGenerationReferenceSchema)
       .max(IMAGE_GENERATION_MAX_REFERENCES)
       .optional()
-      .default([]),
+      .default([])
+      .describe(
+        "Ordered image references. Every sandbox path, File, or artifact must resolve to PNG, JPEG, or WebP bytes.",
+      ),
   })
   .strict();
 export type GenerateImageToolInput = z.infer<typeof GenerateImageToolInput>;