@opengeni/contracts 4.1.0 → 5.0.0

package/src/knowledge-entries.ts

@@ -66,6 +66,8 @@ export const KnowledgeEntrySource = z
     version: z.string().min(1).max(2048).optional(),
     capturedAt: z.string().datetime({ offset: true }).optional(),
     retention: z.enum(["full_text", "passages", "reference"]).optional(),
+    /** Supporting evidence stays retrievable by ID without entering default discovery. */
+    purpose: z.enum(["evidence", "reference"]).optional(),
   })
   .strict();
 export type KnowledgeEntrySource = z.infer<typeof KnowledgeEntrySource>;
@@ -252,6 +254,8 @@ export const KnowledgeEntryListRequest = z
     /** Top-level entries with no visible collection in the selected scope. */
     rootOnly: z.boolean().optional(),
     fileId: z.uuid().optional(),
+    /** Include supporting sources in published discovery; never changes access. */
+    includeEvidence: z.boolean().optional(),
     kind: KnowledgeEntryKind.optional(),
     view: z.enum(["published", "needs_review", "archived", "rejected"]).default("published"),
     sessionId: z.uuid().optional(),

package/src/knowledge-preparation.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { KnowledgeEntryListResponse, KnowledgeEntryScope } from "./knowledge-entries";
+
+/** Read-only discovery before a model decides whether and where to save. */
+export const KnowledgeSavePreparationRequest = z
+  .object({
+    query: z.string().trim().min(1).max(4096),
+    limit: z.number().int().positive().max(20).default(8),
+    collectionCursors: z
+      .object({
+        published: z.string().min(1).max(2048).nullable(),
+        needs_review: z.string().min(1).max(2048).nullable(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export type KnowledgeSavePreparationRequest = z.input<typeof KnowledgeSavePreparationRequest>;
+
+export const KnowledgeCollectionDescriptor = z
+  .object({
+    id: z.uuid(),
+    revisionId: z.uuid(),
+    version: z.number().int().positive(),
+    scope: KnowledgeEntryScope,
+    view: z.enum(["published", "needs_review"]),
+    title: z.string(),
+    description: z.string(),
+    descriptionTruncated: z.boolean(),
+    parentIds: z.array(z.uuid()),
+  })
+  .strict();
+
+export const KnowledgeSavePreparationResponse = z
+  .object({
+    collections: z.object({
+      entries: z.array(KnowledgeCollectionDescriptor),
+      complete: z.boolean(),
+      nextCursors: z.object({
+        published: z.string().nullable(),
+        needs_review: z.string().nullable(),
+      }),
+    }),
+    matches: z.object({
+      published: KnowledgeEntryListResponse,
+      needs_review: KnowledgeEntryListResponse,
+    }),
+  })
+  .strict();
+export type KnowledgeSavePreparationResponse = z.infer<typeof KnowledgeSavePreparationResponse>;

package/src/managed-sign-in-methods.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+
+export const ManagedSignInProvider = z.enum(["google", "github"]);
+export const ManagedSignInMethods = z.object({
+  identityId: z.string().uuid(),
+  email: z.string().email(),
+  emailVerified: z.boolean(),
+  identityRevision: z.number().int().positive(),
+  freshAuthenticationRequired: z.boolean(),
+  methods: z.array(
+    z.object({
+      provider: z.enum(["credential", "google", "github"]),
+      connected: z.boolean(),
+      available: z.boolean(),
+      canDisconnect: z.boolean(),
+      implicitRelinkingSuppressed: z.boolean(),
+    }),
+  ),
+});
+export type ManagedSignInMethods = z.infer<typeof ManagedSignInMethods>;
+export const ManagedSignInMutation = z.object({
+  expectedIdentityId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  expectedIdentityRevision: z.number().int().positive(),
+});
+export const ManagedSignInProviderMutation = ManagedSignInMutation.extend({
+  provider: ManagedSignInProvider,
+}).strict();
+export const ManagedSignInPasswordMutation = ManagedSignInMutation.extend({
+  newPassword: z.string().min(8).max(128),
+  currentPassword: z.string().min(1).max(1024).optional(),
+}).strict();
+export const ManagedSignInMutationResponse = z.object({
+  reauthenticationRequired: z.literal(true),
+  notification: z.enum(["sent", "failed", "outcome_unknown"]),
+});
+export const ManagedSignInConnectResponse = z.object({ url: z.string().url() });

package/src/mcp-oauth.ts

@@ -8,24 +8,22 @@ export const MCP_OAUTH_CONSENT_TTL_SECONDS = 10 * 60;
 
 const RedirectUri = z.string().url().max(2_048);
 
-export const McpOAuthClientRegistrationRequest = z
-  .object({
-    redirect_uris: z.array(RedirectUri).min(1).max(16),
-    client_name: z.string().trim().min(1).max(200).optional(),
-    application_type: z.enum(["native", "web"]).optional(),
-    token_endpoint_auth_method: z.literal("none").default("none"),
-    scope: z.literal(MCP_OAUTH_SCOPE).optional(),
-    grant_types: z
-      .array(z.enum(["authorization_code", "refresh_token"]))
-      .min(1)
-      .max(2)
-      .refine((grantTypes) => grantTypes.includes("authorization_code"), {
-        message: "authorization_code grant is required",
-      })
-      .default(["authorization_code", "refresh_token"]),
-    response_types: z.array(z.literal("code")).min(1).max(1).default(["code"]),
-  })
-  .strict();
+export const McpOAuthClientRegistrationRequest = z.object({
+  redirect_uris: z.array(RedirectUri).min(1).max(16),
+  client_name: z.string().trim().min(1).max(200).optional(),
+  application_type: z.enum(["native", "web"]).optional(),
+  token_endpoint_auth_method: z.literal("none").default("none"),
+  scope: z.literal(MCP_OAUTH_SCOPE).optional(),
+  grant_types: z
+    .array(z.enum(["authorization_code", "refresh_token"]))
+    .min(1)
+    .max(2)
+    .refine((grantTypes) => grantTypes.includes("authorization_code"), {
+      message: "authorization_code grant is required",
+    })
+    .default(["authorization_code", "refresh_token"]),
+  response_types: z.array(z.literal("code")).min(1).max(1).default(["code"]),
+});
 export type McpOAuthClientRegistrationRequest = z.infer<typeof McpOAuthClientRegistrationRequest>;
 
 export const McpOAuthClientRegistrationResponse = McpOAuthClientRegistrationRequest.extend({

package/src/organization-integration-policy.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+/** Catalog identities, never endpoint/domain matching. Custom transports are explicit categories. */
+export const OrganizationIntegrationKey = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(/^[a-z0-9][a-z0-9._:-]*$/);
+const keys = z
+  .array(OrganizationIntegrationKey)
+  .max(10000)
+  .refine((values) => new Set(values).size === values.length, "Duplicate integration identities");
+export const OrganizationIntegrationPolicy = z
+  .object({
+    mode: z.enum(["unrestricted", "restricted"]).default("unrestricted"),
+    allowedIntegrationKeys: keys.default([]),
+    revision: z.number().int().nonnegative().safe().default(0),
+  })
+  .strict();
+export type OrganizationIntegrationPolicy = z.infer<typeof OrganizationIntegrationPolicy>;
+
+export const UpdateOrganizationIntegrationPolicyRequest = z
+  .object({
+    mode: z.enum(["unrestricted", "restricted"]),
+    allowedIntegrationKeys: keys,
+    expectedRevision: z
+      .number()
+      .int()
+      .nonnegative()
+      .max(Number.MAX_SAFE_INTEGER - 1),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type UpdateOrganizationIntegrationPolicyRequest = z.infer<
+  typeof UpdateOrganizationIntegrationPolicyRequest
+>;
+
+export class OrganizationIntegrationDeniedError extends Error {
+  constructor() {
+    super("Integration acquisition is not allowed by organization policy");
+    this.name = "OrganizationIntegrationDeniedError";
+  }
+}
+
+/** integrationKey must come from trusted classification, not client-supplied metadata. */
+export function assertOrganizationIntegrationAllowed(
+  policy: OrganizationIntegrationPolicy,
+  integrationKey: string | null,
+): void {
+  if (policy.mode === "unrestricted") return;
+  if (integrationKey === null || !policy.allowedIntegrationKeys.includes(integrationKey)) {
+    throw new OrganizationIntegrationDeniedError();
+  }
+}

package/src/organization-usage.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+export const OrganizationUsagePeriod = z.enum(["today", "week", "month", "ytd"]);
+export type OrganizationUsagePeriod = z.infer<typeof OrganizationUsagePeriod>;
+export const OrganizationUsageQuery = z.object({
+  period: OrganizationUsagePeriod.default("month"),
+});
+export const OrganizationUsageWorkspacePageQuery = OrganizationUsageQuery.extend({
+  until: z.string().datetime(),
+  afterWorkspaceId: z.string().uuid().optional(),
+});
+// PostgreSQL SUM(bigint) must never pass through a JavaScript number.
+export const OrganizationUsageTotal = z.object({
+  eventType: z.string(),
+  unit: z.string(),
+  quantity: z.string().regex(/^-?\d+$/),
+  eventCount: z.string().regex(/^\d+$/),
+});
+export const OrganizationUsageSummary = z.object({
+  accountId: z.string().uuid(),
+  period: OrganizationUsagePeriod,
+  since: z.string().datetime(),
+  until: z.string().datetime(),
+  granularity: z.enum(["hour", "day"]),
+  totals: z.array(OrganizationUsageTotal),
+  buckets: z.array(z.object({ bucket: z.string(), totals: z.array(OrganizationUsageTotal) })),
+  workspaces: z
+    .array(
+      z.object({
+        workspaceId: z.string().uuid(),
+        name: z.string().nullable(),
+        totals: z.array(OrganizationUsageTotal),
+      }),
+    )
+    .max(50),
+  nextWorkspaceCursor: z.string().uuid().nullable(),
+});
+export type OrganizationUsageSummary = z.infer<typeof OrganizationUsageSummary>;
+
+/** A page deliberately excludes totals and charts: those are not recomputed. */
+export const OrganizationUsageWorkspacePage = OrganizationUsageSummary.omit({
+  totals: true,
+  buckets: true,
+});
+export type OrganizationUsageWorkspacePage = z.infer<typeof OrganizationUsageWorkspacePage>;

package/src/sandbox-provider-command.ts

@@ -13,7 +13,7 @@ const ModalOutputCursor = z
 
 /** Provider-owned execution identity and acknowledged output cursors. These
  * values are retained by the control plane, never recovered from sandbox files. */
-export const SandboxProviderCommand = z
+export const ModalLegacyProviderCommand = z
   .object({
     kind: z.literal("modal-control-v1"),
     sandboxId: z.string().min(1).max(200),
@@ -23,4 +23,60 @@ export const SandboxProviderCommand = z
     streams: z.object({ stdout: ModalOutputCursor, stderr: ModalOutputCursor }).strict(),
   })
   .strict();
+export type ModalLegacyProviderCommand = z.infer<typeof ModalLegacyProviderCommand>;
+
+const ModalByteCursor = z
+  .object({
+    byteOffset: z.number().int().nonnegative().safe(),
+    utf8Remainder: z
+      .string()
+      .max(8)
+      .regex(/^[A-Za-z0-9+/]*={0,2}$/u),
+    eof: z.boolean(),
+    exitCode: z.number().int().nullable(),
+  })
+  .strict()
+  .refine((cursor) => cursor.exitCode === null || cursor.eof, {
+    message: "A terminal output cursor must have reached EOF",
+  });
+
+export const CommandSupervisionDescriptor = z
+  .object({
+    protocol: z.literal("native-subreaper-v1"),
+    invocationId: z.string().uuid(),
+    nonce: z.string().regex(/^[a-f0-9]{64}$/u),
+    controlPath: z.string().regex(/^\/tmp\/opengeni-supervision\/[a-f0-9-]{36}\.sock$/u),
+  })
+  .strict();
+export type CommandSupervisionDescriptor = z.infer<typeof CommandSupervisionDescriptor>;
+
+export const CommandSupervisionReceipt = z
+  .object({
+    protocol: z.literal("native-subreaper-v1"),
+    invocationId: z.string().uuid(),
+    receiptId: z.string().uuid(),
+    leaderExitCode: z.number().int(),
+  })
+  .strict();
+export type CommandSupervisionReceipt = z.infer<typeof CommandSupervisionReceipt>;
+
+export const ModalRouterProviderCommand = z
+  .object({
+    kind: z.literal("modal-router-v1"),
+    sandboxId: z.string().min(1).max(200),
+    taskId: z.string().min(1).max(200),
+    execId: z.string().uuid(),
+    pty: z.boolean().optional(),
+    supervision: CommandSupervisionDescriptor.optional(),
+    streams: z.object({ stdout: ModalByteCursor, stderr: ModalByteCursor }).strict(),
+  })
+  .strict();
+export type ModalRouterProviderCommand = z.infer<typeof ModalRouterProviderCommand>;
+
+/** Legacy locators are read-only compatibility for already launched commands;
+ * new starts use authenticated task-router byte offsets, never batch indices. */
+export const SandboxProviderCommand = z.discriminatedUnion("kind", [
+  ModalLegacyProviderCommand,
+  ModalRouterProviderCommand,
+]);
 export type SandboxProviderCommand = z.infer<typeof SandboxProviderCommand>;

package/src/sandbox-recovery.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+
+/** Public, content-free selection. Never include native provider bindings. */
+export const SandboxRecoverySelection = z
+  .object({
+    version: z.literal(1),
+    sessionId: z.string().uuid(),
+    sandboxGroupId: z.string().uuid(),
+    leaseId: z.string().uuid(),
+    routeEpoch: z.number().int().nonnegative(),
+    authorityEpoch: z.number().int().positive(),
+    leaseEpoch: z.number().int().nonnegative(),
+    workspaceGeneration: z.number().int().nonnegative(),
+    archiveGeneration: z.number().int().nonnegative(),
+    artifactId: z.string().uuid(),
+    revision: z.string().min(1).max(512),
+    capturedAt: z.string().datetime(),
+  })
+  .strict();
+export type SandboxRecoverySelection = z.infer<typeof SandboxRecoverySelection>;
+
+export const SandboxRecoveryProjection = z
+  .object({
+    version: z.literal(1),
+    status: z.enum([
+      "unsupported",
+      "blocked",
+      "eligible",
+      "consent_accepted",
+      "restoring",
+      "restored",
+    ]),
+    reason: z.string().max(128).nullable(),
+    checkpoint: SandboxRecoverySelection.nullable(),
+    operationId: z.string().uuid().nullable(),
+  })
+  .strict();
+export type SandboxRecoveryProjection = z.infer<typeof SandboxRecoveryProjection>;
+
+export const SandboxRecoveryRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    acceptHistoricalCheckpoint: z.literal(true),
+    selection: SandboxRecoverySelection,
+  })
+  .strict();
+export type SandboxRecoveryRequest = z.infer<typeof SandboxRecoveryRequest>;
+
+export const SandboxRecoveryResponse = z
+  .object({
+    outcome: z.enum(["accepted", "replayed"]),
+    operationId: z.string().uuid(),
+    recovery: SandboxRecoveryProjection,
+  })
+  .strict();
+export type SandboxRecoveryResponse = z.infer<typeof SandboxRecoveryResponse>;
+
+/** Re-injected from durable receipts on every attempt, not lossy transcript state. */
+export function sandboxRecoveryDiscontinuity(selection: SandboxRecoverySelection): string {
+  return `Filesystem discontinuity: the human explicitly consented to restoring this session's workspace from the checkpoint captured at ${selection.capturedAt} (archive generation ${selection.archiveGeneration}, pre-recovery workspace generation ${selection.workspaceGeneration}). Newer filesystem changes are unavailable. The generation gap is not a count of lost files or edits. Conversation and tool receipts remain historical evidence, not proof that their files still exist. External effects are not undone. Verify the current filesystem before relying on previous work. Never automatically replay prior commands or operations with unknown outcomes to rebuild missing files. Consent alone is not proof that restoration succeeded.`;
+}

package/src/session-goal-reports.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+export const SessionGoalReportRequirement = z
+  .object({
+    id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/),
+    title: z
+      .string()
+      .trim()
+      .min(1)
+      .refine(
+        (value) => new TextEncoder().encode(value).byteLength <= 512,
+        "Report title exceeds 512 UTF-8 bytes",
+      ),
+  })
+  .strict();
+export type SessionGoalReportRequirement = z.infer<typeof SessionGoalReportRequirement>;
+
+export const SessionGoalReportRequirements = z
+  .array(SessionGoalReportRequirement)
+  .max(16)
+  .superRefine((requirements, context) => {
+    if (new Set(requirements.map((item) => item.id)).size !== requirements.length) {
+      context.addIssue({ code: "custom", message: "Duplicate report requirement IDs" });
+    }
+  });
+
+export const SessionGoalReportDelivery = z
+  .object({
+    requirementId: SessionGoalReportRequirement.shape.id,
+    artifactId: z
+      .string()
+      .regex(/^[0-9a-f]{32}$/)
+      .refine((value) => !/^0+$/.test(value)),
+    inspectionReceiptId: z.string().uuid(),
+  })
+  .strict();
+export type SessionGoalReportDelivery = z.infer<typeof SessionGoalReportDelivery>;
+export const SessionGoalReportDeliveries = z
+  .array(SessionGoalReportDelivery)
+  .max(16)
+  .superRefine((deliveries, context) => {
+    if (new Set(deliveries.map((item) => item.requirementId)).size !== deliveries.length) {
+      context.addIssue({ code: "custom", message: "Duplicate report delivery requirement IDs" });
+    }
+  });

package/src/session-message-search.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+/** Literal Unicode case-insensitive search, without trimming or normalization. */
+export const SessionMessageSearchRequest = z
+  .object({
+    query: z.string().min(1).max(200),
+    sessionId: z.string().uuid().optional(),
+    groupBy: z.literal("session").optional(),
+    archiveStatus: z.enum(["active", "archived", "all"]).optional(),
+    limit: z.number().int().min(1).max(50).optional(),
+    cursor: z.string().min(1).max(4096).optional(),
+  })
+  .strict()
+  .refine((request) => !request.groupBy || !request.sessionId, {
+    message: "groupBy=session is only supported for workspace search without sessionId",
+    path: ["groupBy"],
+  });
+export type SessionMessageSearchRequest = z.infer<typeof SessionMessageSearchRequest>;
+
+export const SessionMessageSearchMatch = z.object({
+  sessionId: z.string().uuid(),
+  sessionTitle: z.string().nullable(),
+  eventId: z.string().uuid(),
+  sequence: z.number().int().positive(),
+  turnId: z.string().uuid().nullable(),
+  role: z.enum(["user", "assistant"]),
+  messageId: z.string().nullable(),
+  /** All offsets are zero-based UTF-16 code units; ends are exclusive. */
+  messageMatchOffset: z.number().int().nonnegative(),
+  snippet: z.object({
+    text: z.string(),
+    matchStart: z.number().int().nonnegative(),
+    matchEnd: z.number().int().nonnegative(),
+  }),
+});
+export type SessionMessageSearchMatch = z.infer<typeof SessionMessageSearchMatch>;
+
+/** A bounded scan page, not necessarily a full page of matches. Continue even
+ * after an empty page while hasMore is true. Counts describe this live traversal,
+ * not a frozen snapshot; restart to reflect concurrent changes. All non-overlapping
+ * literal occurrences in user messages and completed assistant messages.
+ * With groupBy=session, matches and both matched counts describe one first-hit
+ * representative per matching session, not full message/occurrence totals.
+ */
+export const SessionMessageSearchResponse = z.object({
+  matches: z.array(SessionMessageSearchMatch).max(50),
+  nextCursor: z.string().nullable(),
+  hasMore: z.boolean(),
+  scannedMessages: z.number().int().nonnegative(),
+  matchedMessageCount: z.number().int().nonnegative(),
+  matchedOccurrenceCount: z.number().int().nonnegative(),
+  countIsExact: z.boolean(),
+});
+export type SessionMessageSearchResponse = z.infer<typeof SessionMessageSearchResponse>;

package/src/skill-catalog-context.ts

@@ -0,0 +1,50 @@
+/** Durable, model-visible catalog context. Text markers survive SDK/provider replay. */
+export const SKILL_CATALOG_CONTEXT_PREFIX = "<opengeni_skill_catalog>\n";
+export const SKILL_CATALOG_CONTEXT_SUFFIX = "\n</opengeni_skill_catalog>";
+const GUIDANCE =
+  "This is the current configured Skill index and replaces earlier configured Skill indexes. " +
+  "Entries describe discoverability, not permission or full instructions. " +
+  "Use skill_read for instructions and skill_search for current discovery; tool authorization remains authoritative.\n\n";
+
+export function skillCatalogContextItem(catalog: string): Record<string, unknown> {
+  return {
+    type: "message",
+    role: "developer",
+    content: SKILL_CATALOG_CONTEXT_PREFIX + GUIDANCE + catalog + SKILL_CATALOG_CONTEXT_SUFFIX,
+  };
+}
+
+/** Accept the Chat Completions projection and SDK text-part normalization too. */
+export function readSkillCatalogContext(item: Record<string, unknown>): string | null {
+  if (item.type === "unknown" && item.providerData && typeof item.providerData === "object") {
+    const data = item.providerData as Record<string, unknown>;
+    if (data.type === "message") return readSkillCatalogContext(data);
+  }
+  if (item.type !== "message" || (item.role !== "developer" && item.role !== "system")) return null;
+  const content =
+    typeof item.content === "string"
+      ? item.content
+      : Array.isArray(item.content) &&
+          item.content.every(
+            (part) =>
+              part &&
+              (part.type === "input_text" || part.type === "output_text" || part.type === "text") &&
+              typeof part.text === "string",
+          )
+        ? item.content.map((part) => part.text).join("")
+        : null;
+  const prefix = SKILL_CATALOG_CONTEXT_PREFIX + GUIDANCE;
+  return content?.startsWith(prefix) && content.endsWith(SKILL_CATALOG_CONTEXT_SUFFIX)
+    ? content.slice(prefix.length, -SKILL_CATALOG_CONTEXT_SUFFIX.length)
+    : null;
+}
+
+export function latestSkillCatalogContext(
+  items: readonly Record<string, unknown>[],
+): Record<string, unknown> | undefined {
+  for (let index = items.length - 1; index >= 0; index--) {
+    const catalog = readSkillCatalogContext(items[index]!);
+    if (catalog !== null) return skillCatalogContextItem(catalog);
+  }
+  return undefined;
+}

package/src/skills.ts

@@ -38,6 +38,7 @@ export type SkillSaveInput = SkillWriteContext & {
   reason: string;
 };
 export type SkillRevisionInput = SkillWriteContext & {
+  removalOperationId?: string | undefined;
   operationId: string;
   skillId: string;
   revisionId: string;
@@ -45,12 +46,20 @@ export type SkillRevisionInput = SkillWriteContext & {
   expectedScopeVersion: number;
   reason: string;
 };
+export type SkillRemoveInput = SkillWriteContext & {
+  operationId: string;
+  skillId: string;
+  expectedRevisionId: string | null;
+  expectedScopeVersion: number;
+  reason: string;
+};
 export type SkillInstallInput = SkillWriteContext & {
   operationId: string;
   skillFacetId: string;
   reason: string;
 };
 export const SkillReviewReference = z.object({
+  removalOperationId: z.uuid().optional(),
   sourceOperationId: z.uuid(),
   skillId: z.uuid(),
   revisionId: z.uuid(),
@@ -59,18 +68,22 @@ export const SkillReviewReference = z.object({
 });
 export type SkillReviewReference = z.infer<typeof SkillReviewReference>;
 export function skillReviewHumanInput(skillReview: SkillReviewReference) {
+  const removing = Boolean(skillReview.removalOperationId);
   return {
     questions: [
       {
         id: `skill:${skillReview.revisionId}`,
         kind: "single_select" as const,
-        label: "Save this Skill?",
-        prompt: "Save this exact Skill revision for this workspace?",
-        helpText:
-          "Review the complete files before saving. Saving activates this revision immediately.",
+        label: removing ? "Permanently delete this Skill?" : "Save this Skill?",
+        prompt: removing
+          ? "Permanently delete this Skill and all its stored revisions?"
+          : "Save this exact Skill revision for this workspace?",
+        helpText: removing
+          ? "This cannot be undone. All stored Skill revisions will be deleted; conversations remain unchanged."
+          : "Review the complete files before saving. Saving activates this revision immediately.",
         options: [
-          { id: "save", label: "Save" },
-          { id: "skip", label: "Don't save" },
+          { id: "save", label: removing ? "Permanently delete" : "Save" },
+          { id: "skip", label: removing ? "Keep Skill" : "Don't save" },
         ],
         required: true,
         allowOther: false,
@@ -80,6 +93,7 @@ export function skillReviewHumanInput(skillReview: SkillReviewReference) {
   };
 }
 export const SkillWriteReceipt = z.object({
+  removed: z.boolean().optional(),
   operationId: z.uuid(),
   skillId: z.uuid(),
   revisionId: z.uuid(),
@@ -104,6 +118,7 @@ export const SkillSourceReleaseReceipt = z.object({
 });
 export type SkillSourceReleaseReceipt = z.infer<typeof SkillSourceReleaseReceipt>;
 export type SkillRecord = {
+  removalOperationId?: string | null;
   activationMode: "workspace_managed" | "session_selected";
   pendingRevisionIds: string[];
   id: string;