@sequenceholdings/artifact-studio 0.8.0 → 0.9.0

package/dist/server/agent-responses.d.ts

@@ -0,0 +1,425 @@
+import { z } from 'zod';
+import type { ArtifactServerMode, ArtifactServerRequest } from './broker-contract.js';
+/** Mirrors the platform's completed response contract; cross-package fixtures protect this boundary. */
+export declare const artifactCompletedAgentResponseSchema: z.ZodObject<{
+    runId: z.ZodString;
+    agent: z.ZodString;
+    threadId: z.ZodString;
+    status: z.ZodLiteral<"completed">;
+    output: z.ZodJSONSchema;
+    messages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"assistant">;
+        parts: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"dynamic-tool">;
+            output: z.ZodObject<{
+                content: z.ZodArray<z.ZodObject<{
+                    type: z.ZodLiteral<"resource">;
+                    resource: z.ZodObject<{
+                        uri: z.ZodString;
+                        text: z.ZodString;
+                    }, z.core.$strict>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+        }, z.core.$strict>]>>;
+        metadata: z.ZodOptional<z.ZodObject<{
+            citations: z.ZodArray<z.ZodJSONSchema>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    conversation: z.ZodOptional<z.ZodObject<{
+        messageCount: z.ZodNumber;
+        userMessageCount: z.ZodNumber;
+        assistantMessageCount: z.ZodNumber;
+        messages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            role: z.ZodEnum<{
+                user: "user";
+                assistant: "assistant";
+            }>;
+            textParts: z.ZodArray<z.ZodString>;
+            tools: z.ZodArray<z.ZodObject<{
+                partType: z.ZodString;
+                toolName: z.ZodNullable<z.ZodString>;
+                state: z.ZodNullable<z.ZodString>;
+                outputTruthy: z.ZodBoolean;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ArtifactCompletedAgentRun = z.infer<typeof artifactCompletedAgentResponseSchema>;
+export declare const artifactCompletedAgentConversationSchema: z.ZodObject<{
+    runId: z.ZodString;
+    agent: z.ZodString;
+    threadId: z.ZodString;
+    status: z.ZodLiteral<"completed">;
+    output: z.ZodJSONSchema;
+    messages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"assistant">;
+        parts: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"dynamic-tool">;
+            output: z.ZodObject<{
+                content: z.ZodArray<z.ZodObject<{
+                    type: z.ZodLiteral<"resource">;
+                    resource: z.ZodObject<{
+                        uri: z.ZodString;
+                        text: z.ZodString;
+                    }, z.core.$strict>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+        }, z.core.$strict>]>>;
+        metadata: z.ZodOptional<z.ZodObject<{
+            citations: z.ZodArray<z.ZodJSONSchema>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    conversation: z.ZodOptional<z.ZodObject<{
+        messageCount: z.ZodNumber;
+        userMessageCount: z.ZodNumber;
+        assistantMessageCount: z.ZodNumber;
+        messages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            role: z.ZodEnum<{
+                user: "user";
+                assistant: "assistant";
+            }>;
+            textParts: z.ZodArray<z.ZodString>;
+            tools: z.ZodArray<z.ZodObject<{
+                partType: z.ZodString;
+                toolName: z.ZodNullable<z.ZodString>;
+                state: z.ZodNullable<z.ZodString>;
+                outputTruthy: z.ZodBoolean;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    context: z.ZodObject<{
+        messages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            role: z.ZodEnum<{
+                user: "user";
+                assistant: "assistant";
+            }>;
+            parts: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                type: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodString;
+                toolName: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+                toolCallId: z.ZodOptional<z.ZodString>;
+                state: z.ZodOptional<z.ZodString>;
+                input: z.ZodOptional<z.ZodJSONSchema>;
+                output: z.ZodOptional<z.ZodJSONSchema>;
+            }, z.core.$strict>]>>;
+            metadata: z.ZodOptional<z.ZodObject<{
+                citations: z.ZodArray<z.ZodJSONSchema>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        compactionSummary: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const artifactCompletedAgentSourceCaptureSchema: z.ZodObject<{
+    responseHash: z.ZodString;
+    sourceReceipt: z.ZodString;
+    response: z.ZodObject<{
+        runId: z.ZodString;
+        agent: z.ZodString;
+        threadId: z.ZodString;
+        status: z.ZodLiteral<"completed">;
+        output: z.ZodJSONSchema;
+        messages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            role: z.ZodLiteral<"assistant">;
+            parts: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                type: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"dynamic-tool">;
+                output: z.ZodObject<{
+                    content: z.ZodArray<z.ZodObject<{
+                        type: z.ZodLiteral<"resource">;
+                        resource: z.ZodObject<{
+                            uri: z.ZodString;
+                            text: z.ZodString;
+                        }, z.core.$strict>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>;
+            }, z.core.$strict>]>>;
+            metadata: z.ZodOptional<z.ZodObject<{
+                citations: z.ZodArray<z.ZodJSONSchema>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        conversation: z.ZodOptional<z.ZodObject<{
+            messageCount: z.ZodNumber;
+            userMessageCount: z.ZodNumber;
+            assistantMessageCount: z.ZodNumber;
+            messages: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                role: z.ZodEnum<{
+                    user: "user";
+                    assistant: "assistant";
+                }>;
+                textParts: z.ZodArray<z.ZodString>;
+                tools: z.ZodArray<z.ZodObject<{
+                    partType: z.ZodString;
+                    toolName: z.ZodNullable<z.ZodString>;
+                    state: z.ZodNullable<z.ZodString>;
+                    outputTruthy: z.ZodBoolean;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const artifactCompletedAgentConversationCaptureSchema: z.ZodObject<{
+    responseHash: z.ZodString;
+    sourceReceipt: z.ZodString;
+    response: z.ZodObject<{
+        runId: z.ZodString;
+        agent: z.ZodString;
+        threadId: z.ZodString;
+        status: z.ZodLiteral<"completed">;
+        output: z.ZodJSONSchema;
+        messages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            role: z.ZodLiteral<"assistant">;
+            parts: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                type: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"dynamic-tool">;
+                output: z.ZodObject<{
+                    content: z.ZodArray<z.ZodObject<{
+                        type: z.ZodLiteral<"resource">;
+                        resource: z.ZodObject<{
+                            uri: z.ZodString;
+                            text: z.ZodString;
+                        }, z.core.$strict>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>;
+            }, z.core.$strict>]>>;
+            metadata: z.ZodOptional<z.ZodObject<{
+                citations: z.ZodArray<z.ZodJSONSchema>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        conversation: z.ZodOptional<z.ZodObject<{
+            messageCount: z.ZodNumber;
+            userMessageCount: z.ZodNumber;
+            assistantMessageCount: z.ZodNumber;
+            messages: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                role: z.ZodEnum<{
+                    user: "user";
+                    assistant: "assistant";
+                }>;
+                textParts: z.ZodArray<z.ZodString>;
+                tools: z.ZodArray<z.ZodObject<{
+                    partType: z.ZodString;
+                    toolName: z.ZodNullable<z.ZodString>;
+                    state: z.ZodNullable<z.ZodString>;
+                    outputTruthy: z.ZodBoolean;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        context: z.ZodObject<{
+            messages: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                role: z.ZodEnum<{
+                    user: "user";
+                    assistant: "assistant";
+                }>;
+                parts: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                    type: z.ZodLiteral<"text">;
+                    text: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    type: z.ZodString;
+                    toolName: z.ZodOptional<z.ZodString>;
+                    name: z.ZodOptional<z.ZodString>;
+                    toolCallId: z.ZodOptional<z.ZodString>;
+                    state: z.ZodOptional<z.ZodString>;
+                    input: z.ZodOptional<z.ZodJSONSchema>;
+                    output: z.ZodOptional<z.ZodJSONSchema>;
+                }, z.core.$strict>]>>;
+                metadata: z.ZodOptional<z.ZodObject<{
+                    citations: z.ZodArray<z.ZodJSONSchema>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            compactionSummary: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const artifactAgentConversationSourceCaptureSchema: z.ZodObject<{
+    responseHash: z.ZodString;
+    sourceReceipt: z.ZodString;
+    response: z.ZodObject<{
+        agent: z.ZodString;
+        threadId: z.ZodString;
+        revision: z.ZodNumber;
+        cutoffAt: z.ZodISODateTime;
+        context: z.ZodObject<{
+            messages: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                role: z.ZodEnum<{
+                    user: "user";
+                    assistant: "assistant";
+                }>;
+                parts: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                    type: z.ZodLiteral<"text">;
+                    text: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    type: z.ZodString;
+                    toolName: z.ZodOptional<z.ZodString>;
+                    name: z.ZodOptional<z.ZodString>;
+                    toolCallId: z.ZodOptional<z.ZodString>;
+                    state: z.ZodOptional<z.ZodString>;
+                    input: z.ZodOptional<z.ZodJSONSchema>;
+                    output: z.ZodOptional<z.ZodJSONSchema>;
+                }, z.core.$strict>]>>;
+                metadata: z.ZodOptional<z.ZodObject<{
+                    citations: z.ZodArray<z.ZodJSONSchema>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            compactionSummary: z.ZodNull;
+        }, z.core.$strict>;
+        conversation: z.ZodObject<{
+            messageCount: z.ZodNumber;
+            userMessageCount: z.ZodNumber;
+            assistantMessageCount: z.ZodNumber;
+            messages: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                role: z.ZodEnum<{
+                    user: "user";
+                    assistant: "assistant";
+                }>;
+                textParts: z.ZodArray<z.ZodString>;
+                tools: z.ZodArray<z.ZodObject<{
+                    partType: z.ZodString;
+                    toolName: z.ZodNullable<z.ZodString>;
+                    state: z.ZodNullable<z.ZodString>;
+                    outputTruthy: z.ZodBoolean;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ArtifactCompletedAgentSourceCapture = z.infer<typeof artifactCompletedAgentSourceCaptureSchema>;
+export type ArtifactCompletedAgentConversationCapture = z.infer<typeof artifactCompletedAgentConversationCaptureSchema>;
+export type ArtifactAgentConversationSourceCapture = z.infer<typeof artifactAgentConversationSourceCaptureSchema>;
+export declare const artifactCompletedWorkflowSourceCaptureSchema: z.ZodObject<{
+    responseHash: z.ZodString;
+    sourceReceipt: z.ZodString;
+    response: z.ZodObject<{
+        workflow: z.ZodString;
+        runId: z.ZodString;
+        status: z.ZodLiteral<"completed">;
+        output: z.ZodJSONSchema;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ArtifactCompletedWorkflowSourceCapture = z.infer<typeof artifactCompletedWorkflowSourceCaptureSchema>;
+export interface ArtifactServerAgents {
+    createJob(input: ArtifactCreateAgentJob): Promise<ArtifactCreatedAgentJob>;
+    createWorkflowJob(input: ArtifactCreateWorkflowJob): Promise<ArtifactCreatedWorkflowJob>;
+    getCurrentIdentity(query: {
+        kind: 'agent' | 'workflow';
+        id: string;
+    }): Promise<ArtifactExecutionIdentity>;
+    getCompletedRun(query: {
+        agent: string;
+        runId: string;
+    }): Promise<ArtifactCompletedAgentRun>;
+    captureCompletedRun(query: {
+        agent: string;
+        runId: string;
+    }): Promise<ArtifactCompletedAgentSourceCapture>;
+    captureCompletedConversation(query: {
+        agent: string;
+        runId: string;
+    }): Promise<ArtifactCompletedAgentConversationCapture>;
+    captureConversation(query: {
+        agent: string;
+        threadId: string;
+    }): Promise<ArtifactAgentConversationSourceCapture>;
+    captureCompletedWorkflow(query: {
+        workflow: string;
+        runId: string;
+    }): Promise<ArtifactCompletedWorkflowSourceCapture>;
+}
+export declare const artifactExecutionIdentitySchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+    definitionSha256: z.ZodString;
+}, z.core.$strict>;
+export type ArtifactExecutionIdentity = z.infer<typeof artifactExecutionIdentitySchema>;
+declare const createAgentJobSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    messages: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        role: z.ZodEnum<{
+            user: "user";
+            system: "system";
+            assistant: "assistant";
+        }>;
+        content: z.ZodOptional<z.ZodString>;
+        parts: z.ZodOptional<z.ZodArray<z.ZodJSONSchema>>;
+        fileIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    expectedIdentity: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+        definitionSha256: z.ZodString;
+    }, z.core.$strict>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+declare const createWorkflowJobSchema: z.ZodObject<{
+    workflowId: z.ZodString;
+    input: z.ZodJSONSchema;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    expectedIdentity: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+        definitionSha256: z.ZodString;
+    }, z.core.$strict>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+declare const createdAgentJobSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent">;
+    threadId: z.ZodString;
+    jobId: z.ZodString;
+    triggerId: z.ZodString;
+    status: z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        completed: "completed";
+    }>;
+}, z.core.$strict>;
+declare const createdWorkflowJobSchema: z.ZodObject<{
+    type: z.ZodLiteral<"workflow">;
+    workflowId: z.ZodString;
+    jobId: z.ZodString;
+    triggerId: z.ZodString;
+    status: z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        completed: "completed";
+    }>;
+}, z.core.$strict>;
+export type ArtifactCreateAgentJob = z.infer<typeof createAgentJobSchema>;
+export type ArtifactCreateWorkflowJob = z.infer<typeof createWorkflowJobSchema>;
+export type ArtifactCreatedAgentJob = z.infer<typeof createdAgentJobSchema>;
+export type ArtifactCreatedWorkflowJob = z.infer<typeof createdWorkflowJobSchema>;
+/** User mode only; the manifest declares each exact route and Atlas enforces its current source access floor. */
+export declare function createArtifactAgentsClient({ mode, json }: {
+    mode: ArtifactServerMode;
+    json: (operation: ArtifactServerRequest) => Promise<unknown>;
+}): ArtifactServerAgents;
+export {};

package/dist/server/agent-responses.js

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { ArtifactServerError } from './errors.js';
+const resourceId = z.string().min(1).max(255).regex(/^[A-Za-z0-9._-]+$/);
+/** Mirrors the platform's completed response contract; cross-package fixtures protect this boundary. */
+export const artifactCompletedAgentResponseSchema = z.strictObject({
+    runId: resourceId, agent: resourceId, threadId: resourceId, status: z.literal('completed'), output: z.json(),
+    messages: z.array(z.strictObject({
+        id: z.string().min(1).max(255), role: z.literal('assistant'),
+        parts: z.array(z.union([
+            z.strictObject({ type: z.literal('text'), text: z.string() }),
+            z.strictObject({ type: z.literal('dynamic-tool'), output: z.strictObject({ content: z.array(z.strictObject({ type: z.literal('resource'), resource: z.strictObject({ uri: z.string().startsWith('citation://'), text: z.string() }) })).max(1000) }) }),
+        ])).max(1000),
+        metadata: z.strictObject({ citations: z.array(z.json()).max(1000) }).optional(),
+    })).max(1000),
+    conversation: z.strictObject({
+        messageCount: z.number().int().min(0).max(1000), userMessageCount: z.number().int().min(0).max(1000), assistantMessageCount: z.number().int().min(0).max(1000),
+        messages: z.array(z.strictObject({ id: z.string().min(1).max(255), role: z.enum(['user', 'assistant']), textParts: z.array(z.string()).max(1000), tools: z.array(z.strictObject({ partType: z.string().min(1).max(255), toolName: z.string().max(255).nullable(), state: z.string().max(255).nullable(), outputTruthy: z.boolean() })).max(1000) })).max(1000),
+    }).optional(),
+});
+const conversationToolPart = z.strictObject({
+    type: z.string().min(1).max(255).refine((type) => type !== 'tool-result' && (type === 'dynamic-tool' || type === 'tool-invocation' || type.startsWith('tool-')), 'Only tool parts are permitted'),
+    toolName: z.string().max(255).optional(), name: z.string().max(255).optional(), toolCallId: z.string().min(1).max(255).optional(), state: z.string().max(255).optional(),
+    input: z.json().optional(), output: z.json().optional(),
+});
+export const artifactCompletedAgentConversationSchema = artifactCompletedAgentResponseSchema.extend({
+    context: z.strictObject({
+        messages: z.array(z.strictObject({
+            id: z.string().min(1).max(255), role: z.enum(['user', 'assistant']),
+            parts: z.array(z.union([z.strictObject({ type: z.literal('text'), text: z.string() }), conversationToolPart])).max(1000),
+            metadata: z.strictObject({ citations: z.array(z.json()).max(1000) }).optional(),
+        })).max(1000),
+        compactionSummary: z.string().nullable(),
+    }),
+});
+const sourceFields = { responseHash: z.string().regex(/^[a-f0-9]{64}$/), sourceReceipt: z.string().min(1).max(16_384) };
+export const artifactCompletedAgentSourceCaptureSchema = z.strictObject({ response: artifactCompletedAgentResponseSchema, ...sourceFields });
+export const artifactCompletedAgentConversationCaptureSchema = z.strictObject({ response: artifactCompletedAgentConversationSchema, ...sourceFields });
+export const artifactAgentConversationSourceCaptureSchema = z.strictObject({
+    response: z.strictObject({
+        agent: resourceId, threadId: resourceId, revision: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER), cutoffAt: z.iso.datetime({ offset: true }),
+        context: artifactCompletedAgentConversationSchema.shape.context.extend({ compactionSummary: z.null() }),
+        conversation: artifactCompletedAgentResponseSchema.shape.conversation.unwrap(),
+    }),
+    ...sourceFields,
+});
+export const artifactCompletedWorkflowSourceCaptureSchema = z.strictObject({ response: z.strictObject({ workflow: resourceId, runId: resourceId, status: z.literal('completed'), output: z.json() }), ...sourceFields });
+export const artifactExecutionIdentitySchema = z.strictObject({
+    id: z.string().min(1).max(128).regex(/^[A-Za-z0-9_-]+$/), version: z.string().min(1).max(128),
+    definitionSha256: z.string().regex(/^[a-f0-9]{64}$/),
+});
+const idempotencyKeySchema = z.string().min(1).max(128).regex(/^[\x21-\x7e]+$/);
+const jobMessageSchema = z.strictObject({
+    id: z.string().optional(), role: z.enum(['user', 'assistant', 'system']),
+    content: z.string().optional(), parts: z.array(z.json()).optional(),
+    fileIds: z.array(resourceId).optional(), metadata: z.record(z.string(), z.json()).optional(),
+}).refine((message) => Boolean(message.content?.length || message.parts?.length), 'A job message requires content or parts');
+const createAgentJobSchema = z.strictObject({
+    agentId: resourceId, messages: z.array(jobMessageSchema).min(1), metadata: z.record(z.string(), z.json()).optional(),
+    expectedIdentity: artifactExecutionIdentitySchema, idempotencyKey: idempotencyKeySchema,
+});
+const createWorkflowJobSchema = z.strictObject({
+    workflowId: resourceId, input: z.json(), metadata: z.record(z.string(), z.json()).optional(),
+    expectedIdentity: artifactExecutionIdentitySchema, idempotencyKey: idempotencyKeySchema,
+});
+const createdJobFields = { jobId: resourceId, triggerId: resourceId,
+    status: z.enum(['queued', 'running', 'completed', 'failed', 'cancelled']) };
+const createdAgentJobSchema = z.strictObject({ ...createdJobFields, type: z.literal('agent'), threadId: resourceId });
+const createdWorkflowJobSchema = z.strictObject({ ...createdJobFields, type: z.literal('workflow'), workflowId: resourceId });
+/** User mode only; the manifest declares each exact route and Atlas enforces its current source access floor. */
+export function createArtifactAgentsClient({ mode, json }) {
+    async function read(query, endpoint) {
+        if (mode !== 'user')
+            throw new ArtifactServerError(403, 'operation_not_allowed', 'Completed agent sources require user mode');
+        const { agent, runId } = z.strictObject({ agent: resourceId, runId: resourceId }).parse(query);
+        const path = `/api/agents/jobs/${encodeURIComponent(runId)}/${endpoint}?${new URLSearchParams({ agent })}`;
+        return json({ operation: 'api', mode, method: 'GET', path });
+    }
+    function matches(response, query) {
+        return response.runId === query.runId && response.agent === query.agent;
+    }
+    return {
+        async createJob(input) {
+            if (mode !== 'user')
+                throw new ArtifactServerError(403, 'operation_not_allowed', 'Job admission requires user mode');
+            const body = createAgentJobSchema.parse(input);
+            if (body.expectedIdentity.id !== body.agentId)
+                throw new ArtifactServerError(400, 'invalid_request', 'The agent source identity does not match its job');
+            const parsed = createdAgentJobSchema.safeParse(await json({ operation: 'api', mode, method: 'POST', path: '/api/agents/jobs/create-idempotent', body }));
+            if (!parsed.success)
+                throw new ArtifactServerError(502, 'invalid_response', 'Atlas returned an invalid agent job admission');
+            return parsed.data;
+        },
+        async createWorkflowJob(input) {
+            if (mode !== 'user')
+                throw new ArtifactServerError(403, 'operation_not_allowed', 'Job admission requires user mode');
+            const { workflowId, ...body } = createWorkflowJobSchema.parse(input);
+            if (body.expectedIdentity.id !== workflowId)
+                throw new ArtifactServerError(400, 'invalid_request', 'The workflow source identity does not match its job');
+            const parsed = createdWorkflowJobSchema.safeParse(await json({ operation: 'api', mode, method: 'POST',
+                path: `/api/agents/workflows/${encodeURIComponent(workflowId)}/jobs`, body }));
+            if (!parsed.success || parsed.data.workflowId !== workflowId)
+                throw new ArtifactServerError(502, 'invalid_response', 'Atlas returned an invalid workflow job admission');
+            return parsed.data;
+        },
+        async getCurrentIdentity(query) {
+            if (mode !== 'user')
+                throw new ArtifactServerError(403, 'operation_not_allowed', 'Execution source identity requires user mode');
+            const { kind, id } = z.strictObject({ kind: z.enum(['agent', 'workflow']), id: resourceId }).parse(query);
+            const path = `/api/agents/${kind === 'agent' ? 'agents' : 'workflows'}/${encodeURIComponent(id)}/current-identity`;
+            const parsed = artifactExecutionIdentitySchema.safeParse(await json({ operation: 'api', mode, method: 'GET', path }));
+            if (!parsed.success || parsed.data.id !== id)
+                throw new ArtifactServerError(502, 'invalid_response', 'Atlas returned an invalid execution source identity');
+            return parsed.data;
+        },
+        async getCompletedRun(query) {
+            const parsed = artifactCompletedAgentResponseSchema.safeParse(await read(query, 'completed-response'));
+            if (!parsed.success || !matches(parsed.data, query))
+                throw new ArtifactServerError(502, 'invalid_response', 'Atlas returned an invalid completed agent response');
+            return parsed.data;
+        },
+        async captureCompletedRun(query) {
+            const parsed = artifactCompletedAgentSourceCaptureSchema.safeParse(await read(query, 'completed-source'));
+            if (!parsed.success || !matches(parsed.data.response, query))
+                throw new ArtifactServerError(502, 'invalid_response', 'Atlas returned an invalid completed source capture');
+            return parsed.data;
+        },
+        async captureCompletedConversation(query) {
+            const parsed = artifactCompletedAgentConversationCaptureSchema.safeParse(await read(query, 'completed-conversation'));
+            if (!parsed.success || !matches(parsed.data.response, query))
+                throw new ArtifactServerError(502, 'invalid_response', 'Atlas returned an invalid completed conversation capture');
+            return parsed.data;
+        },
+        async captureCompletedWorkflow(query) {
+            if (mode !== 'user')
+                throw new ArtifactServerError(403, 'operation_not_allowed', 'Workflow sources require user mode');
+            const { workflow, runId } = z.strictObject({ workflow: resourceId, runId: resourceId }).parse(query);
+            const path = `/api/agents/jobs/${encodeURIComponent(runId)}/completed-workflow-source?${new URLSearchParams({ workflow })}`;
+            const parsed = artifactCompletedWorkflowSourceCaptureSchema.safeParse(await json({ operation: 'api', mode, method: 'GET', path }));
+            if (!parsed.success || parsed.data.response.workflow !== workflow || parsed.data.response.runId !== runId)
+                throw new ArtifactServerError(502, 'invalid_response', 'Atlas returned an invalid completed workflow source');
+            return parsed.data;
+        },
+        async captureConversation(query) {
+            if (mode !== 'user')
+                throw new ArtifactServerError(403, 'operation_not_allowed', 'Conversation sources require user mode');
+            const { agent, threadId } = z.strictObject({ agent: resourceId, threadId: resourceId }).parse(query);
+            const path = `/api/agents/threads/${encodeURIComponent(threadId)}/conversation-source?${new URLSearchParams({ agent })}`;
+            const parsed = artifactAgentConversationSourceCaptureSchema.safeParse(await json({ operation: 'api', mode, method: 'GET', path }));
+            if (!parsed.success || parsed.data.response.agent !== agent || parsed.data.response.threadId !== threadId)
+                throw new ArtifactServerError(502, 'invalid_response', 'Atlas returned an invalid conversation source capture');
+            return parsed.data;
+        },
+    };
+}

package/dist/server/broker-contract.d.ts

@@ -109,6 +109,11 @@ export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.Zod
     }>>;
     process: z.ZodString;
     runId: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    expectedProcess: z.ZodOptional<z.ZodObject<{
+        version: z.ZodString;
+        bundleHash: z.ZodString;
+    }, z.core.$strict>>;
     startNodeId: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
     entity: z.ZodOptional<z.ZodObject<{

package/dist/server/broker-contract.js

@@ -27,6 +27,8 @@ const id = z.string().min(1).max(255).regex(/^[a-zA-Z0-9_-]+$/);
 const latticeId = z.string().min(2).max(128).regex(/^[A-Za-z0-9._-]+$/);
 // A process version is the registry's own label (the bundle hash prefix today); FGA-safe class.
 const latticeVersion = z.string().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/);
+// An assertion on the resolved immutable target, independent of the optional version selector.
+const expectedProcessIdentity = z.object({ version: latticeVersion, bundleHash: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
 /** A Lattice run's lifecycle status, as `GET /api/lattice/runs` filters it. */
 export const ARTIFACT_PROCESS_RUN_STATUSES = ['pending', 'running', 'completed', 'failed', 'cancelled', 'timed_out'];
 /** Lattice lists at most this many runs per call. */
@@ -128,10 +130,12 @@ export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
     z.object({ operation: z.literal('function'), mode, id, params: z.record(z.string(), z.unknown()).optional() }).strict(),
     // Starts a run of a declared process, as `POST /api/lattice/runs` does: the application names the
     // run, passes its input, may seed who works each human node and may enter the graph at a node
-    // other than the process's start (the route's `start_node_id`). The version and engine stay with
-    // the process and its owning routes.
+    // other than the process's start (the route's `start_node_id`). A registered version may be
+    // selected explicitly; omitting it follows the active version. The engine stays server-owned.
     z.object({
         operation: z.literal('lattice'), mode, process: latticeId, runId: latticeId.optional(),
+        version: latticeVersion.optional(),
+        expectedProcess: expectedProcessIdentity.optional(),
         startNodeId: z.string().min(1).max(255).regex(/^[A-Za-z0-9._-]+$/).optional(),
         title: z.string().max(500).optional(),
         entity: z.object({ type: entityRef, id: entityRef }).strict().optional(),

package/dist/server/client.d.ts

@@ -8,6 +8,7 @@ import { createArtifactLogger, type ArtifactLogRecord } from './logger.js';
 import { type ArtifactRequestContext, type RequestContextV2External } from './request-context.js';
 import { type ArtifactExternalAccept } from './external-context.js';
 import { createApiClient } from './api-client.js';
+import { type ArtifactServerAgents } from './agent-responses.js';
 import { type ArtifactPrincipal } from './principal.js';
 import { type ArtifactRuntimeConfig, type ArtifactRequestHeaders } from './runtime-config.js';
 export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './errors.js';
@@ -79,6 +80,7 @@ export interface ArtifactServerClient<TContext extends ArtifactServerContext = A
     mode: ArtifactServerMode;
     log: ReturnType<typeof createArtifactLogger>;
     api: ReturnType<typeof createApiClient>;
+    agents: ArtifactServerAgents;
     storage: ReturnType<typeof storageClient>;
     functions: {
         invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>): Promise<TOutput>;