@opengeni/contracts 2.9.2 → 2.13.0-canary.0

package/dist/session-titles.js

@@ -4,14 +4,20 @@ import {
   SESSION_TITLE_MAX_CHARACTERS,
   boundAutomaticSessionTitle,
   containsSensitiveAutomaticSessionTitleValue,
-  normalizeAutomaticSessionTitle
-} from "./chunk-4IVHBXRI.js";
+  deriveAutomaticSessionTitlePreview,
+  deriveSessionDisplayTitle,
+  normalizeAutomaticSessionTitle,
+  sessionTitleIsPending
+} from "./chunk-7ABONTXE.js";
 export {
   AUTOMATIC_SESSION_TITLE_FALLBACK,
   AUTOMATIC_SESSION_TITLE_MAX_GRAPHEMES,
   SESSION_TITLE_MAX_CHARACTERS,
   boundAutomaticSessionTitle,
   containsSensitiveAutomaticSessionTitleValue,
-  normalizeAutomaticSessionTitle
+  deriveAutomaticSessionTitlePreview,
+  deriveSessionDisplayTitle,
+  normalizeAutomaticSessionTitle,
+  sessionTitleIsPending
 };
 //# sourceMappingURL=session-titles.js.map

package/dist/tool-catalog.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 export declare const ATTEMPT_TOOL_CATALOG_VERSION: 1;
+export declare const TOOL_GATEWAY_CATALOG_VERSION: 1;
 export declare const ATTEMPT_TOOL_CATALOG_MAX_ENTRIES = 4096;
 export declare const ATTEMPT_TOOL_CATALOG_MAX_BYTES: number;
 export declare const ATTEMPT_TOOL_CATALOG_MAX_PATH_SEGMENTS = 8;
@@ -17,6 +18,12 @@ export declare const AttemptToolIdentity: z.ZodObject<{
     toolName: z.ZodString;
 }, z.core.$strict>;
 export type AttemptToolIdentity = z.infer<typeof AttemptToolIdentity>;
+/** Protocol-neutral tool identity shared by MCP, HTTP/SDK, agents, and Codemode. */
+export declare const ToolGatewayIdentity: z.ZodObject<{
+    serverId: z.ZodString;
+    toolName: z.ZodString;
+}, z.core.$strict>;
+export type ToolGatewayIdentity = AttemptToolIdentity;
 export declare const AttemptToolCatalogIcon: z.ZodObject<{
     src: z.ZodString;
     mimeType: z.ZodOptional<z.ZodString>;
@@ -81,6 +88,110 @@ export declare const AttemptToolCatalogEntry: z.ZodObject<{
     }>;
 }, z.core.$strict>;
 export type AttemptToolCatalogEntry = z.infer<typeof AttemptToolCatalogEntry>;
+/** One canonical gateway entry. Adapter-specific names are projections, never authority. */
+export declare const ToolGatewayCatalogEntry: z.ZodObject<{
+    identity: z.ZodObject<{
+        serverId: z.ZodString;
+        toolName: z.ZodString;
+    }, z.core.$strict>;
+    modelName: z.ZodString;
+    codemodePath: z.ZodArray<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    annotations: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+        destructiveHint: z.ZodOptional<z.ZodBoolean>;
+        idempotentHint: z.ZodOptional<z.ZodBoolean>;
+        openWorldHint: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        src: z.ZodString;
+        mimeType: z.ZodOptional<z.ZodString>;
+        sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        theme: z.ZodOptional<z.ZodEnum<{
+            dark: "dark";
+            light: "light";
+        }>>;
+    }, z.core.$strict>>>;
+    source: z.ZodEnum<{
+        codex_apps: "codex_apps";
+        docs: "docs";
+        files: "files";
+        interaction: "interaction";
+        mcp: "mcp";
+        opengeni: "opengeni";
+    }>;
+    approval: z.ZodEnum<{
+        human: "human";
+        none: "none";
+        policy: "policy";
+    }>;
+}, z.core.$strict>;
+export type ToolGatewayCatalogEntry = AttemptToolCatalogEntry;
+export declare const ToolGatewayCatalog: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    accountId: z.ZodString;
+    workspaceId: z.ZodString;
+    generation: z.ZodNumber;
+    digest: z.ZodString;
+    createdAt: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        identity: z.ZodObject<{
+            serverId: z.ZodString;
+            toolName: z.ZodString;
+        }, z.core.$strict>;
+        modelName: z.ZodString;
+        codemodePath: z.ZodArray<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        inputSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        annotations: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+            destructiveHint: z.ZodOptional<z.ZodBoolean>;
+            idempotentHint: z.ZodOptional<z.ZodBoolean>;
+            openWorldHint: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            src: z.ZodString;
+            mimeType: z.ZodOptional<z.ZodString>;
+            sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            theme: z.ZodOptional<z.ZodEnum<{
+                dark: "dark";
+                light: "light";
+            }>>;
+        }, z.core.$strict>>>;
+        source: z.ZodEnum<{
+            codex_apps: "codex_apps";
+            docs: "docs";
+            files: "files";
+            interaction: "interaction";
+            mcp: "mcp";
+            opengeni: "opengeni";
+        }>;
+        approval: z.ZodEnum<{
+            human: "human";
+            none: "none";
+            policy: "policy";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ToolGatewayCatalog = z.infer<typeof ToolGatewayCatalog>;
+export declare const ToolGatewayCaller: z.ZodObject<{
+    kind: z.ZodEnum<{
+        browser: "browser";
+        codemode: "codemode";
+        http: "http";
+        mcp: "mcp";
+        model: "model";
+    }>;
+    subjectId: z.ZodString;
+}, z.core.$strict>;
+export type ToolGatewayCaller = z.infer<typeof ToolGatewayCaller>;
 export declare const AttemptToolCatalog: z.ZodObject<{
     version: z.ZodLiteral<1>;
     accountId: z.ZodString;
@@ -328,6 +439,166 @@ export declare const AttemptToolResult: z.ZodObject<{
     _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
 }, z.core.$loose>;
 export type AttemptToolResult = z.infer<typeof AttemptToolResult>;
+export declare const ToolGatewayResult: z.ZodObject<{
+    content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+        annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        data: z.ZodString;
+        mimeType: z.ZodString;
+        annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"audio">;
+        data: z.ZodString;
+        mimeType: z.ZodString;
+        annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"resource_link">;
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        uri: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+        icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            src: z.ZodString;
+            mimeType: z.ZodOptional<z.ZodString>;
+            sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            theme: z.ZodOptional<z.ZodEnum<{
+                dark: "dark";
+                light: "light";
+            }>>;
+        }, z.core.$strict>>>;
+        annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"resource">;
+        resource: z.ZodUnion<readonly [z.ZodObject<{
+            uri: z.ZodString;
+            mimeType: z.ZodOptional<z.ZodString>;
+            text: z.ZodString;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        }, z.core.$loose>, z.ZodObject<{
+            uri: z.ZodString;
+            mimeType: z.ZodOptional<z.ZodString>;
+            blob: z.ZodString;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        }, z.core.$loose>]>;
+        annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$loose>], "type">>;
+    structuredContent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    isError: z.ZodOptional<z.ZodBoolean>;
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$loose>;
+export type ToolGatewayResult = AttemptToolResult;
+export declare const ToolGatewayCallRequest: z.ZodObject<{
+    operationId: z.ZodOptional<z.ZodString>;
+    catalogDigest: z.ZodString;
+    identity: z.ZodObject<{
+        serverId: z.ZodString;
+        toolName: z.ZodString;
+    }, z.core.$strict>;
+    arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    siteArtifactId: z.ZodOptional<z.ZodString>;
+    siteVersionId: z.ZodOptional<z.ZodString>;
+    approvalToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ToolGatewayCallRequest = z.infer<typeof ToolGatewayCallRequest>;
+export declare const ToolGatewayApprovalRequest: z.ZodObject<{
+    operationId: z.ZodString;
+    catalogDigest: z.ZodString;
+    identity: z.ZodObject<{
+        serverId: z.ZodString;
+        toolName: z.ZodString;
+    }, z.core.$strict>;
+    arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+}, z.core.$strict>;
+export type ToolGatewayApprovalRequest = z.infer<typeof ToolGatewayApprovalRequest>;
+export declare const ToolGatewayApprovalResponse: z.ZodObject<{
+    operationId: z.ZodString;
+    catalogDigest: z.ZodString;
+    identity: z.ZodObject<{
+        serverId: z.ZodString;
+        toolName: z.ZodString;
+    }, z.core.$strict>;
+    approvalToken: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strict>;
+export type ToolGatewayApprovalResponse = z.infer<typeof ToolGatewayApprovalResponse>;
+export declare const ToolGatewayCallResponse: z.ZodObject<{
+    operationId: z.ZodString;
+    catalogDigest: z.ZodString;
+    result: z.ZodObject<{
+        content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+            annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            data: z.ZodString;
+            mimeType: z.ZodString;
+            annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"audio">;
+            data: z.ZodString;
+            mimeType: z.ZodString;
+            annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"resource_link">;
+            name: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            uri: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            mimeType: z.ZodOptional<z.ZodString>;
+            size: z.ZodOptional<z.ZodNumber>;
+            icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                src: z.ZodString;
+                mimeType: z.ZodOptional<z.ZodString>;
+                sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                theme: z.ZodOptional<z.ZodEnum<{
+                    dark: "dark";
+                    light: "light";
+                }>>;
+            }, z.core.$strict>>>;
+            annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"resource">;
+            resource: z.ZodUnion<readonly [z.ZodObject<{
+                uri: z.ZodString;
+                mimeType: z.ZodOptional<z.ZodString>;
+                text: z.ZodString;
+                _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            }, z.core.$loose>, z.ZodObject<{
+                uri: z.ZodString;
+                mimeType: z.ZodOptional<z.ZodString>;
+                blob: z.ZodString;
+                _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            }, z.core.$loose>]>;
+            annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        }, z.core.$loose>], "type">>;
+        structuredContent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        isError: z.ZodOptional<z.ZodBoolean>;
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$loose>;
+}, z.core.$strict>;
+export type ToolGatewayCallResponse = z.infer<typeof ToolGatewayCallResponse>;
+export declare const ToolGatewayDeclarationsResponse: z.ZodObject<{
+    catalogDigest: z.ZodString;
+    moduleSpecifier: z.ZodString;
+    source: z.ZodString;
+}, z.core.$strict>;
+export type ToolGatewayDeclarationsResponse = z.infer<typeof ToolGatewayDeclarationsResponse>;
 export declare const CodemodeOperationState: z.ZodEnum<{
     cancelled: "cancelled";
     completed: "completed";

package/dist/workspace-learning-policy.d.ts

@@ -3,7 +3,7 @@ export declare const WORKSPACE_LEARNING_POLICY_MAX_SOURCE_OVERRIDES = 256;
 export declare const WORKSPACE_LEARNING_POLICY_SOURCE_KIND_MAX_CHARS = 96;
 export declare const WORKSPACE_LEARNING_POLICY_SOURCE_ID_MAX_CHARS = 1024;
 export declare const WORKSPACE_LEARNING_POLICY_REASON_MAX_CHARS = 4096;
-export declare const WORKSPACE_LEARNING_POLICY_DEFAULT_OFF_REVISION_ID = "workspace-learning-policy:default-off:v1";
+export declare const WORKSPACE_LEARNING_POLICY_DEFAULT_SUGGEST_REVISION_ID = "workspace-learning-policy:default-suggest:v1";
 export declare const WorkspaceLearningMode: z.ZodEnum<{
     automatic: "automatic";
     off: "off";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "2.9.2",
+  "version": "2.13.0-canary.0",
   "description": "Shared zod schemas and wire-contract types for the OpenGeni API.",
   "license": "Apache-2.0",
   "repository": {
@@ -34,6 +34,14 @@
       "types": "./dist/personal-github.d.ts",
       "import": "./dist/personal-github.js"
     },
+    "./github-repository": {
+      "types": "./dist/github-repository.d.ts",
+      "import": "./dist/github-repository.js"
+    },
+    "./github-repository-contracts": {
+      "types": "./dist/github-repository-contracts.d.ts",
+      "import": "./dist/github-repository-contracts.js"
+    },
     "./atlassian": {
       "types": "./dist/atlassian.d.ts",
       "import": "./dist/atlassian.js"
@@ -78,6 +86,10 @@
       "types": "./dist/xai-provider-account-authority.d.ts",
       "import": "./dist/xai-provider-account-authority.js"
     },
+    "./model-picker-order": {
+      "types": "./dist/model-picker-order.d.ts",
+      "import": "./dist/model-picker-order.js"
+    },
     "./editable-artifacts": {
       "types": "./dist/editable-artifacts.d.ts",
       "import": "./dist/editable-artifacts.js"

package/src/artifacts.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
+import { ToolGatewayIdentity } from "./tool-catalog";
 
 export const WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES = 4 * 1024 * 1024;
+export const WORKSPACE_ARTIFACT_SOURCE_MAX_UTF8_BYTES = 4 * 1024 * 1024;
+export const WORKSPACE_ARTIFACT_SOURCE_MAX_FILES = 128;
+export const WORKSPACE_ARTIFACT_REQUESTED_TOOLS_MAX = 128;
 export const WORKSPACE_ARTIFACT_TITLE_MAX_CHARS = 120;
 export const WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS = 2_000;
 export const WORKSPACE_ARTIFACT_LIST_MAX = 100;
@@ -21,6 +25,84 @@ export type WorkspaceArtifactSlug = z.infer<typeof WorkspaceArtifactSlug>;
 export const WorkspaceArtifactStatus = z.enum(["active", "archived"]);
 export type WorkspaceArtifactStatus = z.infer<typeof WorkspaceArtifactStatus>;
 
+export const WorkspaceArtifactSourcePath = z
+  .string()
+  .min(1)
+  .max(256)
+  .regex(/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/u)
+  .refine(
+    (value) =>
+      !value
+        .split("/")
+        .some((segment) => segment === "." || segment === ".." || segment.length === 0),
+    { message: "artifact source paths must be relative and traversal-free" },
+  );
+export type WorkspaceArtifactSourcePath = z.infer<typeof WorkspaceArtifactSourcePath>;
+
+export const WorkspaceArtifactSourceFile = z
+  .object({
+    path: WorkspaceArtifactSourcePath,
+    content: z.string(),
+  })
+  .strict();
+export type WorkspaceArtifactSourceFile = z.infer<typeof WorkspaceArtifactSourceFile>;
+
+/** Retained editable source; the published runtime remains one exact HTML document. */
+export const WorkspaceArtifactSourceBundle = z
+  .object({
+    entrypoint: WorkspaceArtifactSourcePath,
+    files: z.array(WorkspaceArtifactSourceFile).min(1).max(WORKSPACE_ARTIFACT_SOURCE_MAX_FILES),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const paths = new Set<string>();
+    for (const [index, file] of value.files.entries()) {
+      if (paths.has(file.path)) {
+        context.addIssue({
+          code: "custom",
+          path: ["files", index, "path"],
+          message: "artifact source file paths must be unique",
+        });
+      }
+      paths.add(file.path);
+    }
+    if (!paths.has(value.entrypoint)) {
+      context.addIssue({
+        code: "custom",
+        path: ["entrypoint"],
+        message: "artifact source entrypoint must name one retained file",
+      });
+    }
+    if (
+      encoder.encode(JSON.stringify(value)).byteLength > WORKSPACE_ARTIFACT_SOURCE_MAX_UTF8_BYTES
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: `artifact source exceeds ${WORKSPACE_ARTIFACT_SOURCE_MAX_UTF8_BYTES} UTF-8 bytes`,
+      });
+    }
+  });
+export type WorkspaceArtifactSourceBundle = z.infer<typeof WorkspaceArtifactSourceBundle>;
+
+export const WorkspaceArtifactRequestedTools = z
+  .array(ToolGatewayIdentity)
+  .max(WORKSPACE_ARTIFACT_REQUESTED_TOOLS_MAX)
+  .superRefine((tools, context) => {
+    const seen = new Set<string>();
+    for (const [index, identity] of tools.entries()) {
+      const key = `${identity.serverId}\u0000${identity.toolName}`;
+      if (seen.has(key)) {
+        context.addIssue({
+          code: "custom",
+          path: [index],
+          message: "requested artifact tools must be unique",
+        });
+      }
+      seen.add(key);
+    }
+  });
+export type WorkspaceArtifactRequestedTools = z.infer<typeof WorkspaceArtifactRequestedTools>;
+
 export const WorkspaceArtifactVersion = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -30,6 +112,14 @@ export const WorkspaceArtifactVersion = z.object({
   contentType: z.literal("text/html"),
   contentSha256: sha256,
   sizeBytes: z.number().int().positive().max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES),
+  sourceSha256: sha256.nullable(),
+  sourceSizeBytes: z
+    .number()
+    .int()
+    .positive()
+    .max(WORKSPACE_ARTIFACT_SOURCE_MAX_UTF8_BYTES)
+    .nullable(),
+  requestedTools: WorkspaceArtifactRequestedTools,
   sourceSessionId: z.string().uuid().nullable(),
   sourceTurnId: z.string().uuid().nullable(),
   sourceAttemptId: z.string().uuid().nullable(),
@@ -54,7 +144,12 @@ export const WorkspaceArtifact = z.object({
 });
 export type WorkspaceArtifact = z.infer<typeof WorkspaceArtifact>;
 
-export const WorkspaceArtifactEventType = z.enum(["published", "rolled_back"]);
+export const WorkspaceArtifactEventType = z.enum([
+  "published",
+  "rolled_back",
+  "archived",
+  "restored",
+]);
 export type WorkspaceArtifactEventType = z.infer<typeof WorkspaceArtifactEventType>;
 
 export const WorkspaceArtifactEvent = z.object({
@@ -83,6 +178,7 @@ export const WorkspaceArtifactListQuery = z.object({
     .max(WORKSPACE_ARTIFACT_LIST_MAX)
     .default(WORKSPACE_ARTIFACT_LIST_DEFAULT),
   cursor: z.string().min(1).max(WORKSPACE_ARTIFACT_CURSOR_MAX_CHARS).optional(),
+  status: WorkspaceArtifactStatus.optional(),
 });
 export type WorkspaceArtifactListQuery = z.infer<typeof WorkspaceArtifactListQuery>;
 
@@ -120,6 +216,8 @@ export const CreateWorkspaceArtifactRequest = z.object({
   title: z.string().trim().min(1).max(WORKSPACE_ARTIFACT_TITLE_MAX_CHARS),
   description: z.string().max(WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS).nullable().optional(),
   html: WorkspaceArtifactHtml,
+  source: WorkspaceArtifactSourceBundle.optional(),
+  requestedTools: WorkspaceArtifactRequestedTools.optional(),
   idempotencyKey: z.string().trim().min(1).max(200),
 });
 export type CreateWorkspaceArtifactRequest = z.infer<typeof CreateWorkspaceArtifactRequest>;
@@ -128,6 +226,8 @@ export const PublishWorkspaceArtifactVersionRequest = z.object({
   title: z.string().trim().min(1).max(WORKSPACE_ARTIFACT_TITLE_MAX_CHARS).optional(),
   description: z.string().max(WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS).nullable().optional(),
   html: WorkspaceArtifactHtml,
+  source: WorkspaceArtifactSourceBundle.optional(),
+  requestedTools: WorkspaceArtifactRequestedTools.optional(),
   expectedCurrentVersionId: z.string().uuid(),
   idempotencyKey: z.string().trim().min(1).max(200),
 });
@@ -143,6 +243,14 @@ export const RollbackWorkspaceArtifactRequest = z.object({
 });
 export type RollbackWorkspaceArtifactRequest = z.infer<typeof RollbackWorkspaceArtifactRequest>;
 
+export const SetWorkspaceArtifactStatusRequest = z.object({
+  status: WorkspaceArtifactStatus,
+  expectedCurrentVersionId: z.string().uuid(),
+  reason: z.string().trim().min(1).max(4096),
+  idempotencyKey: z.string().trim().min(1).max(200),
+});
+export type SetWorkspaceArtifactStatusRequest = z.infer<typeof SetWorkspaceArtifactStatusRequest>;
+
 export const WorkspaceArtifactMutationResponse = z.object({
   artifact: WorkspaceArtifact,
   version: WorkspaceArtifactVersion,
@@ -157,6 +265,8 @@ export const WorkspaceArtifactContentResponse = z.object({
   contentType: z.literal("text/html"),
   contentSha256: sha256,
   html: WorkspaceArtifactHtml,
+  source: WorkspaceArtifactSourceBundle,
+  requestedTools: WorkspaceArtifactRequestedTools,
 });
 export type WorkspaceArtifactContentResponse = z.infer<typeof WorkspaceArtifactContentResponse>;
 

package/src/github-repository-contracts.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+
+export const VerifyPublicGitHubRepositoryRefRequest = z
+  .object({
+    url: z.string().min(1).max(2048),
+    ref: z
+      .string()
+      .trim()
+      .min(1)
+      .max(1024)
+      .refine((value) => !/[\u0000-\u001f\u007f]/u.test(value), "ref contains control characters"),
+  })
+  .strict();
+export type VerifyPublicGitHubRepositoryRefRequest = z.infer<
+  typeof VerifyPublicGitHubRepositoryRefRequest
+>;
+
+export const VerifyPublicGitHubRepositoryRefResponse = z
+  .object({
+    owner: z.string().min(1).max(39),
+    name: z.string().min(1).max(100),
+    fullName: z.string().min(3).max(140),
+    canonicalUrl: z.string().url(),
+    cloneUrl: z.string().url(),
+    defaultBranch: z.string().min(1).max(1024),
+    ref: z.string().min(1).max(1024),
+    commitSha: z.string().regex(/^[0-9a-f]{40}$/u),
+  })
+  .strict();
+export type VerifyPublicGitHubRepositoryRefResponse = z.infer<
+  typeof VerifyPublicGitHubRepositoryRefResponse
+>;
+
+export const GITHUB_REPOSITORY_BRANCH_PAGE_MAX = 100 as const;
+
+export const ListGitHubRepositoryBranchesQuery = z
+  .object({
+    cursor: z.coerce.number().int().positive().max(10_000).default(1),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(GITHUB_REPOSITORY_BRANCH_PAGE_MAX)
+      .default(GITHUB_REPOSITORY_BRANCH_PAGE_MAX),
+  })
+  .strict();
+export type ListGitHubRepositoryBranchesQuery = z.infer<typeof ListGitHubRepositoryBranchesQuery>;
+
+export const GitHubRepositoryBranch = z
+  .object({
+    name: z.string().min(1).max(1024),
+    isDefault: z.boolean(),
+  })
+  .strict();
+export type GitHubRepositoryBranch = z.infer<typeof GitHubRepositoryBranch>;
+
+export const GitHubRepositoryBranchesResponse = z
+  .object({
+    branches: z.array(GitHubRepositoryBranch).max(GITHUB_REPOSITORY_BRANCH_PAGE_MAX),
+    nextCursor: z.number().int().positive().max(10_000).nullable(),
+  })
+  .strict()
+  .superRefine((response, context) => {
+    const names = new Set<string>();
+    let defaultCount = 0;
+    response.branches.forEach((branch, index) => {
+      if (names.has(branch.name)) {
+        context.addIssue({
+          code: "custom",
+          path: ["branches", index, "name"],
+          message: "branch names must be unique",
+        });
+      }
+      names.add(branch.name);
+      if (branch.isDefault) defaultCount += 1;
+    });
+    if (defaultCount > 1) {
+      context.addIssue({
+        code: "custom",
+        path: ["branches"],
+        message: "at most one branch may be marked as default",
+      });
+    }
+  });
+export type GitHubRepositoryBranchesResponse = z.infer<typeof GitHubRepositoryBranchesResponse>;

package/src/github-repository.ts

@@ -0,0 +1,59 @@
+export type CanonicalGitHubRepository = {
+  owner: string;
+  name: string;
+  fullName: string;
+  canonicalUrl: string;
+  cloneUrl: string;
+};
+
+/**
+ * Parse only a canonical public github.com repository URL. This deliberately
+ * rejects aliases, credentials, ports, query/fragment state, encoded paths,
+ * and repository subpaths so callers cannot accidentally verify one target
+ * and attach another.
+ */
+export function parseCanonicalGitHubRepositoryUrl(value: string): CanonicalGitHubRepository {
+  if (!value.startsWith("https://github.com/")) {
+    throw new Error("GitHub repository URL must use the exact https://github.com host.");
+  }
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TypeError("GitHub repository URL is invalid.");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.hostname !== "github.com" ||
+    url.host !== "github.com" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname.includes("%")
+  ) {
+    throw new TypeError("Use a canonical https://github.com/owner/repository URL.");
+  }
+  const match = /^\/([^/]+)\/([^/]+?)\/?$/u.exec(url.pathname);
+  if (!match) {
+    throw new TypeError("GitHub repository URL must contain exactly owner/repository.");
+  }
+  const owner = match[1]!;
+  const name = match[2]!.replace(/\.git$/iu, "");
+  if (
+    !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/u.test(owner) ||
+    !/^[A-Za-z0-9_.-]{1,100}$/u.test(name) ||
+    name === "." ||
+    name === ".."
+  ) {
+    throw new TypeError("GitHub repository owner or name is invalid.");
+  }
+  const fullName = `${owner}/${name}`;
+  return {
+    owner,
+    name,
+    fullName,
+    canonicalUrl: `https://github.com/${fullName}`,
+    cloneUrl: `https://github.com/${fullName}.git`,
+  };
+}