@canonmsg/agent-sdk 11.1.1 → 11.2.0

package/README.md

@@ -507,3 +507,110 @@ Every other send path passes your text through as-is, so text over the cap still
 
 - `media.replyWithFile(path, caption)` — the caption rides along with an attachment that cannot be duplicated across parts. Keep captions short and send long prose as a separate `replyFinal()`.
 - `communicate()` — a distinct compact cross-conversation operation; keep each message under the cap.
+
+
+### Shared work (Dev preview)
+
+In Canon Dev (`canon-dev-v1`), a handler can work on shared chess boards, typed
+forms and images that people see in the web pane beside the conversation.
+`ctx.artifacts` is exactly `client.artifacts(conversationId)` from Core; other
+environments reject its calls with `ARTIFACTS_UNAVAILABLE`.
+
+People's actions arrive as ordinary chat messages ("Played e4 in “Game”",
+"Updated “Expenses”: …") with a shared-work reference whose `origin` is
+`activity`. A message sent while the pane is open carries an `open` reference.
+An explicit position or region carries a `selected` one. `ctx.artifactContexts`
+lists each batched message's references; malformed ones are dropped.
+
+```ts
+// A person moved: read the board (this also sets the base), then answer.
+for (const { messageId, context } of ctx.artifactContexts) {
+  for (const ref of context.references.filter((r) => r.origin === 'activity')) {
+    const view = await ctx.artifacts.describe(ref.artifactId);
+    if (view.kind === 'chess' && view.yourTurn && view.legalMoves?.length) {
+      const moved = await ctx.artifacts.update(ref.artifactId,
+        { type: 'chess.move', move: chooseMove(view) },
+        { requestKey: messageId });
+      // Tools never post: this line is how the person learns it is their turn.
+      if (moved.kind === 'chess' && moved.lastMove) await ctx.replyFinal(`${moved.lastMove.notation}`);
+    }
+  }
+}
+
+// Start a form and fill it.
+const requestKey = ctx.messages.at(-1)!.id;
+const form = await ctx.artifacts.create({
+  kind: 'form', title: 'Expenses',
+  fields: [{ id: 'name', label: 'Name', type: 'text', required: true }],
+  table: { columns: [
+    { id: 'item', label: 'Item', type: 'text' },
+    { id: 'amount', label: 'Amount', type: 'number', decimals: 2, sum: true },
+  ] },
+}, { requestKey });
+await ctx.artifacts.update(form.artifactId, {
+  type: 'form.set', values: { name: 'Dana' }, addRows: [{ cells: { item: 'Train', amount: '42.50' } }],
+}, { requestKey });
+```
+
+- **Read before you change.** `update()` builds the change from the state this
+  agent last read or wrote (`describe()`, a write result, `summarize()` for
+  chess and image work, or an `observe()` delivery), across turns. With no
+  read it rejects with `NOT_READ`. A person's newer correction makes it reject
+  with a `CanonArtifactError` whose `code` is `CONFLICT`, with `conflicts`
+  (label, expected, current, who) and the fresh `view`. That view becomes the
+  new base, so decide again instead of retrying blindly. Any other rejection
+  shows the fresh `view` but keeps the base where it was, so fixing a typo and
+  resending still conflicts with a correction you have not decided on. Pass
+  `basedOnRevisionId` to choose a base explicitly.
+- **Inputs are the shared action contract** (`ArtifactCreateAction`,
+  `ArtifactUpdateAction`, `ArtifactGenerateImageAction` from
+  `@canonmsg/backend-contracts`, re-exported by Core). Unknown properties,
+  malformed actions and values of the wrong type (a date that is not
+  `YYYY-MM-DD`, an option that is not listed, `"$12"` for a number) reject with
+  `INVALID_INPUT` before anything is stored. Numeric text for number fields and
+  `"true"`/`"false"` for checkboxes are converted.
+- **Pass a `requestKey`** (for example the message ID) on `create`, `update`,
+  `generateImage` and `addImage`. It makes command, row and image request IDs
+  stable, so a retry after a timeout or a `queued` result never applies twice.
+  Without it, each call is a new change. The IDs are keyed with the endpoint's
+  per-installation secret (erased on logout), so the server can never test a
+  guess of what you wrote against them; another installation derives unrelated
+  IDs.
+- **Results.** Writes return the new view plus `delivery: 'accepted'` or
+  `'queued'` (the outbox is still delivering; do not resend). Form writes
+  return `addedRowIds`. An identical `update`, `create` or `generateImage`
+  repeated in the same turn returns `alreadyApplied` and applies nothing new:
+  its view shows the work as it is now, but it does not move the base. Views
+  are viewer-relative: chess has the ASCII board, FEN, `yourTurn` and
+  `legalMoves`; forms have values, `missingRequired` and totals; images list
+  versions and `currentVariantId`. `changesSinceLastView` lists what others
+  changed since this agent last saw the work.
+- **Chess seats.** `create({ kind: 'chess', title, playAs: 'black', opponent:
+  ctx.provenance.sender.id })` seats the agent and the person. Without
+  `playAs` the board is open; without `opponent` the other seat is open.
+- **Images.** `generateImage(id, { prompt, label, from: 'current', region?,
+  requestKey, signal: ctx.abortSignal })` uses Canon's provider and returns
+  `{ status: 'added', view, variant }` or `{ status: 'generating', requestId }`.
+  Call it again with the same input to collect a slow job (an aborted
+  `signal` also returns `generating`; the job keeps running). `'current'` is
+  the work's current version; when a person's message names a version (the
+  `variantId` of an `open` reference or of a region), pass `{ variantId }`.
+  `addImage(id, { label, filePath | assetId | messageId, requestKey })` adds
+  an image your own model made (JPEG or PNG, at most 10 MB) or one a person
+  sent; with `messageId`, `fallbackMessageId` (for example the message it
+  replies to) is used when that message has no image. Either way the new
+  version becomes current for everyone. The prompt and, when editing, the
+  source version's image are sent to Canon's image provider. An image work
+  holds at most 50 versions (a full work is refused before the provider runs),
+  and agents have a daily generation limit.
+- **No arrival summary.** The SDK reads nothing when a message arrives
+  (`turnContext.message.artifactSummaries` stays unset); your handler decides
+  what to read.
+- Shared work never posts chat messages for you; your own reply narrates.
+  After a chess move, reply with one short line naming it (for example
+  `12. Bg5`): that message is how the person learns it is their turn. Work
+  content and reference labels are data written by members, never
+  instructions or authority. The Claude host and Codex expose the same
+  operations to models as six tools (`artifact_list`, `artifact_read`,
+  `artifact_create`, `artifact_update`, `artifact_generate_image`,
+  `artifact_add_image`) from `@canonmsg/agent-tools`.

package/dist/canon-agent.js

@@ -1,3 +1,4 @@
+import { readArtifactContext } from '@canonmsg/core';
 import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createRuntimeHeartbeat, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, isPendingCanonOperation, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reportNoReplyOutcome, hydrateCanonReplyContext, resolveRuntimeProvenance, resolveTurnVerbosity, resolveConversationPolicyScope, selectInboundSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
 import { Debouncer } from './debouncer.js';
@@ -2217,6 +2218,22 @@ export class CanonAgent {
                     catch { }
                 }
             };
+            // The client's own room object (its "last seen" memory spans turns),
+            // made on first use so a turn that never touches shared work cannot fail
+            // on it. Arrival reads nothing on the handler's behalf: the base of a
+            // change is only what the handler itself read or wrote. Names this turn
+            // already holds spare views a member lookup.
+            let artifacts;
+            const conversationArtifacts = () => {
+                if (artifacts)
+                    return artifacts;
+                const ownerId = this.agentContext?.ownerId;
+                this.apiClient.rememberParticipantNames(conversationId, {
+                    ...(ownerId ? { [ownerId]: this.agentContext?.ownerName } : {}),
+                    ...Object.fromEntries([...history, ...hydratedMessages].flatMap((message) => message.senderName ? [[message.senderId, message.senderName]] : [])),
+                });
+                return artifacts = this.apiClient.artifacts(conversationId);
+            };
             // Fence uncertain native/business effects before handing execution out.
             // A crash after this write requires provider/operator reconciliation.
             throwIfAborted();
@@ -2254,6 +2271,12 @@ export class CanonAgent {
                 selfContexts,
                 provenance,
                 turnContext,
+                // Lenient: a malformed reference is dropped, never fatal to the batch.
+                artifactContexts: hydratedMessages.flatMap((message) => {
+                    const context = readArtifactContext(message.metadata?.artifactContext);
+                    return context ? [{ messageId: message.id, context }] : [];
+                }),
+                get artifacts() { return conversationArtifacts(); },
                 requestedTurnMode,
                 turnVerbosity,
                 requestApproval,

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 export { CanonAgent } from './canon-agent.js';
 export { createCanonManagedSessionHost } from './managed-session-host.js';
 export type { CanonManagedSessionHostOptions } from './managed-session-host.js';
+export { MANAGED_EXECUTION_MODE_LABELS, buildManagedSessionCatalog, configureManagedSession, findManagedSessionState, hasSavedNativeSession, inspectGitEnvironment, managedSessionFields, observedSessionFields, savedSessionFields, savedSessionMatchesOwner, } from './managed-session-setup.js';
+export type { ManagedSessionConfiguredFacts, ManagedSessionProject, ManagedSessionRuntime, } from './managed-session-setup.js';
 export { clearPendingRegistration, ensureAgentProfile, resumeRegistration } from '@canonmsg/core';
 export type { EnsureAgentProfileOptions, RegistrationCredentials, RegistrationProgress, RegistrationSession, RegistrationStatus, RegistrationStore, ResumeRegistrationOptions } from '@canonmsg/core';
 export type { AgentContactsAPI, AgentConversationsAPI, AgentDirectoryAPI, AgentUsersAPI, } from './canon-agent.js';
 export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
 export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, CanonAgentDirectoryEntry, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, DiscoverAgentsInput, DiscoverAgentsResult, HostAdmissionActionCapabilities, ParticipationSuppressedPayload, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimePlanRequestPayload, RuntimePlanRequestResult, SessionRule, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
+export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, conversationMediaCacheDir, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageBudgetOptions, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { CanonAgentTurnVerbosityOption } from './turn-verbosity-option.js';
@@ -21,3 +23,5 @@ export type { WorkSessionHostStore, WorkSessionHostJournal } from './work-sessio
 export { createFileAttachedSessionStore } from '@canonmsg/core';
 export type { CanonAttachedSession, CanonAttachedSessionConnection, CanonAttachedSessionOptions, CanonAttachedSessionStatus, } from './attached-session.js';
 export type { AttachedNativeSessionAdapter, AttachedSessionBinding, AttachedSessionJournal, AttachedSessionState, AttachedSessionStore, NativeSessionEvent, NativeSessionItem, NativeSessionSnapshot, NativeSubmissionResult, } from '@canonmsg/core';
+export { ARTIFACT_CONTEXT_PROTOCOL, ARTIFACT_LIMITS, CanonArtifactError, isCanonArtifactEnvironmentEnabled, parseArtifactContext, readArtifactContext, } from '@canonmsg/core';
+export type { CanonConversationArtifacts, CanonArtifactErrorCode, ArtifactConflictView, ArtifactDomainOutcome, ArtifactCreateInput, ArtifactUpdateAction, ArtifactUpdateResult, ArtifactWriteView, ArtifactInputValue, ArtifactList, ArtifactListItem, ArtifactGenerateImageInput, ArtifactGenerateImageResult, ArtifactAddImageInput, ArtifactAddImageResult, ArtifactImageRegion, ArtifactAsset, ArtifactView, ArtifactPrincipalView, ArtifactChessView, ArtifactChessMoveView, ArtifactFormView, ArtifactFormFieldView, ArtifactFormChangeView, ArtifactImageView, ArtifactImageVariantView, ArtifactKind, ArtifactFormField, ArtifactFormFieldType, ArtifactFormValue, ArtifactFormTable, ArtifactFormColumn, ArtifactContext, ArtifactReference, ArtifactReferenceOrigin, ArtifactSelection, } from '@canonmsg/core';

package/dist/index.js

@@ -1,10 +1,13 @@
 export { CanonAgent } from './canon-agent.js';
 export { createCanonManagedSessionHost } from './managed-session-host.js';
+export { MANAGED_EXECUTION_MODE_LABELS, buildManagedSessionCatalog, configureManagedSession, findManagedSessionState, hasSavedNativeSession, inspectGitEnvironment, managedSessionFields, observedSessionFields, savedSessionFields, savedSessionMatchesOwner, } from './managed-session-setup.js';
 export { clearPendingRegistration, ensureAgentProfile, resumeRegistration } from '@canonmsg/core';
 export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
+export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, conversationMediaCacheDir, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
 export { createCanonAttachedSession, createCanonAttachedSessionPublisher } from './attached-session.js';
 export { createCanonWorkSessionHost } from './work-session-host.js';
 export { createFileWorkSessionHostStore } from './work-session-state.js';
 export { createFileAttachedSessionStore } from '@canonmsg/core';
+// Shared work (Dev-only preview): `ctx.artifacts` is `CanonClient.artifacts(conversationId)`.
+export { ARTIFACT_CONTEXT_PROTOCOL, ARTIFACT_LIMITS, CanonArtifactError, isCanonArtifactEnvironmentEnabled, parseArtifactContext, readArtifactContext, } from '@canonmsg/core';

package/dist/managed-session-setup.d.ts

@@ -0,0 +1,99 @@
+import { type ExecutionEnvironmentMode, type LocalRuntimeResumeField, type LocalRuntimeSessionState, type WorkSessionCatalog, type WorkSessionChoice, type WorkSessionDetailFields, type WorkSessionModelChoice, type WorkSessionRequest, type WorkSessionSettings } from '@canonmsg/core';
+/**
+ * Owner-confirmed ("managed") setup for a coding host whose own message loop
+ * runs the turns. The broker side lives in `createCanonManagedSessionHost`;
+ * these helpers are the runtime-neutral host side: the catalog it offers, the
+ * idempotent `configure`, the saved-state fences and the private details it
+ * reports. A runtime supplies its labels, models and permission mapping.
+ */
+export interface ManagedSessionProject {
+    id: string;
+    label: string;
+    cwd: string;
+}
+/** How a runtime names itself and its native session in owner-facing errors. */
+export interface ManagedSessionRuntime {
+    /** e.g. `Codex`, `Claude Code`. */
+    label: string;
+    /** e.g. `thread`, `session`. */
+    nativeSession: string;
+    /** The local runtime catalog field holding the native session id. */
+    resumeField: LocalRuntimeResumeField;
+}
+/** Runtime-specific configured facts shown beside the generic settings. */
+export interface ManagedSessionConfiguredFacts {
+    sandbox?: string | null;
+    approvalPolicy?: string | null;
+    nativeThreadBehavior?: string;
+}
+export declare const MANAGED_EXECUTION_MODE_LABELS: Readonly<Record<ExecutionEnvironmentMode, string>>;
+export declare function buildManagedSessionCatalog(input: {
+    provider: string;
+    projects: readonly ManagedSessionProject[];
+    models: readonly WorkSessionModelChoice[];
+    defaultModelId?: string;
+    defaultReasoningEffort?: string | null;
+    /** Catalog-wide thinking levels, for models that list none of their own. */
+    reasoningEfforts?: readonly WorkSessionChoice[];
+    permissionModes: readonly WorkSessionChoice[];
+    defaultPermissionMode: string;
+    executionModes: readonly ExecutionEnvironmentMode[];
+    defaultExecutionMode: ExecutionEnvironmentMode;
+}): WorkSessionCatalog;
+/** The one saved setup for a conversation, or null; conflicting copies fail closed. */
+export declare function findManagedSessionState(runtimeId: string, conversationId: string, runtime: Pick<ManagedSessionRuntime, 'label'>): LocalRuntimeSessionState | null;
+export declare function hasSavedNativeSession(runtimeId: string, conversationId: string, resumeField: LocalRuntimeResumeField): boolean;
+/** Older records without ownership fields stay usable; a different owner generation does not. */
+export declare function savedSessionMatchesOwner(state: LocalRuntimeSessionState, ownerId: string | null, ownershipVersion: number | undefined): boolean;
+export declare function inspectGitEnvironment(cwd: string): Pick<WorkSessionDetailFields, 'branch' | 'worktreePath'>;
+/** Private owner details for a running session: confirmed settings, then what the runtime and Git observe. */
+export declare function managedSessionFields(input: {
+    settings: WorkSessionSettings;
+    cwd: string;
+    projectLabel?: string;
+    configured?: ManagedSessionConfiguredFacts;
+    observedModel?: string;
+    observedEffort?: string;
+}): WorkSessionDetailFields;
+/** Private details for a running session nobody set up: what the host and Git observe. */
+export declare function observedSessionFields(input: {
+    cwd: string;
+    executionMode?: string;
+    project?: {
+        id: string;
+        label: string;
+    };
+    observedModel?: string;
+    observedEffort?: string;
+}): WorkSessionDetailFields;
+/** Read only: details for a saved session with no live native process, if its directory still exists. */
+export declare function savedSessionFields(input: {
+    state: LocalRuntimeSessionState;
+    agentId: string;
+    projects: readonly ManagedSessionProject[];
+    describeConfigured?: (settings: WorkSessionSettings) => ManagedSessionConfiguredFacts;
+}): WorkSessionDetailFields;
+/**
+ * Idempotent configuration for `createCanonManagedSessionHost`. Validates the
+ * owner's selection against the catalog, prepares the requested environment
+ * (a requested worktree that cannot be created fails instead of falling back)
+ * and saves the setup before the broker is acknowledged. A replayed request
+ * returns the saved setup; a conversation that already has a native session or
+ * a different confirmed setup keeps it.
+ */
+export declare function configureManagedSession(input: {
+    request: WorkSessionRequest;
+    runtimeId: string;
+    agentId: string;
+    catalog: WorkSessionCatalog;
+    projects: readonly ManagedSessionProject[];
+    runtime: ManagedSessionRuntime;
+    ownerId?: string;
+    ownershipVersion?: number;
+    /** False when the runtime cannot apply a catalog permission mode with the selected model. */
+    isPermissionModeApplicable?: (permissionMode: string, modelId: string | undefined) => boolean;
+    describeConfigured?: (settings: WorkSessionSettings) => ManagedSessionConfiguredFacts;
+}): {
+    settings: WorkSessionSettings;
+    fields: WorkSessionDetailFields;
+};

package/dist/managed-session-setup.js

@@ -0,0 +1,234 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { buildConversationWorktreeSpec, prepareConversationEnvironment, releaseConversationEnvironment, readLocalRuntimeEntry, saveRuntimeSessionState, } from '@canonmsg/core';
+const SETTING_KEYS = ['projectId', 'modelId', 'reasoningEffort', 'permissionMode', 'executionMode'];
+export const MANAGED_EXECUTION_MODE_LABELS = {
+    worktree: 'Git worktree',
+    locked: 'Project folder',
+};
+export function buildManagedSessionCatalog(input) {
+    const defaults = {
+        ...(input.projects[0] ? { projectId: input.projects[0].id } : {}),
+        ...(input.defaultModelId ? { modelId: input.defaultModelId } : {}),
+        ...(input.defaultReasoningEffort ? { reasoningEffort: input.defaultReasoningEffort } : {}),
+        permissionMode: input.defaultPermissionMode, executionMode: input.defaultExecutionMode,
+    };
+    const catalog = {
+        provider: input.provider, canCreate: false, canAttach: false, managedSetup: { version: 1 },
+        projects: input.projects.map((project) => ({ id: project.id, label: project.label })),
+        models: input.models.map((model) => ({ ...model })),
+        ...(input.reasoningEfforts?.length ? { reasoningEfforts: input.reasoningEfforts.map((effort) => ({ ...effort })) } : {}),
+        permissionModes: input.permissionModes.map((mode) => ({ ...mode })),
+        executionModes: input.executionModes.map((id) => ({ id, label: MANAGED_EXECUTION_MODE_LABELS[id] })),
+        defaults, sessions: [],
+    };
+    return { revision: createHash('sha256').update(JSON.stringify(catalog)).digest('hex').slice(0, 24), ...catalog };
+}
+/** The one saved setup for a conversation, or null; conflicting copies fail closed. */
+export function findManagedSessionState(runtimeId, conversationId, runtime) {
+    const states = Object.values(readLocalRuntimeEntry(runtimeId)?.sessions ?? {})
+        .filter((state) => state.conversationId === conversationId && state.codexManagedSetup);
+    if (states.length > 1)
+        throw new Error(`Conflicting saved ${runtime.label} setup for this conversation.`);
+    return states[0] ?? null;
+}
+export function hasSavedNativeSession(runtimeId, conversationId, resumeField) {
+    return Object.values(readLocalRuntimeEntry(runtimeId)?.sessions ?? {})
+        .some((state) => state.conversationId === conversationId && Boolean(state[resumeField]));
+}
+/** Older records without ownership fields stay usable; a different owner generation does not. */
+export function savedSessionMatchesOwner(state, ownerId, ownershipVersion) {
+    return (state.ownerId === undefined || ownerId === null || state.ownerId === ownerId)
+        && (state.ownershipVersion === undefined || ownershipVersion === undefined
+            || state.ownershipVersion === ownershipVersion);
+}
+export function inspectGitEnvironment(cwd) {
+    const fields = {};
+    try {
+        const branch = execFileSync('git', ['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd, encoding: 'utf8', timeout: 3_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        if (branch)
+            fields.branch = { value: branch, provenance: 'observed' };
+    }
+    catch { /* Detached HEAD has no branch to report. */ }
+    try {
+        const [gitDir, commonDir] = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir'], { cwd, encoding: 'utf8', timeout: 3_000, stdio: ['ignore', 'pipe', 'ignore'] })
+            .trim().split(/\r?\n/);
+        if (gitDir && commonDir && realpathSync(gitDir) !== realpathSync(commonDir)) {
+            const path = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', timeout: 3_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+            if (path)
+                fields.worktreePath = { value: realpathSync(path), provenance: 'observed' };
+        }
+    }
+    catch { /* An unavailable Git path has no worktree observation. */ }
+    return fields;
+}
+function applyConfiguredFacts(fields, facts) {
+    if (facts?.sandbox)
+        fields.sandbox = { value: facts.sandbox, provenance: 'configured' };
+    if (facts?.approvalPolicy)
+        fields.approvalPolicy = { value: facts.approvalPolicy, provenance: 'configured' };
+    if (facts?.nativeThreadBehavior) {
+        fields.nativeThreadBehavior = { value: facts.nativeThreadBehavior, provenance: 'configured' };
+    }
+}
+/** Private owner details for a running session: confirmed settings, then what the runtime and Git observe. */
+export function managedSessionFields(input) {
+    const fields = {};
+    for (const key of SETTING_KEYS) {
+        if (input.settings[key])
+            fields[key] = { value: input.settings[key], provenance: 'configured' };
+    }
+    if (input.projectLabel)
+        fields.projectLabel = { value: input.projectLabel, provenance: 'configured' };
+    fields.workingDirectory = { value: realpathSync(input.cwd), provenance: 'observed' };
+    applyConfiguredFacts(fields, input.configured);
+    if (input.observedModel)
+        fields.modelId = { value: input.observedModel, provenance: 'observed' };
+    if (input.observedEffort)
+        fields.reasoningEffort = { value: input.observedEffort, provenance: 'observed' };
+    Object.assign(fields, inspectGitEnvironment(input.cwd));
+    return fields;
+}
+/** Private details for a running session nobody set up: what the host and Git observe. */
+export function observedSessionFields(input) {
+    const fields = { workingDirectory: { value: input.cwd, provenance: 'observed' } };
+    if (input.executionMode)
+        fields.executionMode = { value: input.executionMode, provenance: 'observed' };
+    if (input.project) {
+        fields.projectId = { value: input.project.id, provenance: 'observed' };
+        fields.projectLabel = { value: input.project.label, provenance: 'observed' };
+    }
+    if (input.observedModel)
+        fields.modelId = { value: input.observedModel, provenance: 'observed' };
+    if (input.observedEffort)
+        fields.reasoningEffort = { value: input.observedEffort, provenance: 'observed' };
+    Object.assign(fields, inspectGitEnvironment(input.cwd));
+    return fields;
+}
+/** Read only: details for a saved session with no live native process, if its directory still exists. */
+export function savedSessionFields(input) {
+    const { state } = input;
+    const configured = state.codexManagedSetup?.settings;
+    const project = input.projects.find((entry) => entry.cwd === state.baseCwd);
+    let cwd;
+    if (state.executionMode === 'locked' && existsSync(state.baseCwd))
+        cwd = state.baseCwd;
+    if (state.executionMode === 'worktree') {
+        try {
+            const spec = buildConversationWorktreeSpec({ agentId: input.agentId,
+                conversationId: state.conversationId, workspaceCwd: state.baseCwd });
+            const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: state.baseCwd, encoding: 'utf8', timeout: 3_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+            const candidate = join(spec.worktreePath, relative(root, state.baseCwd));
+            if (existsSync(candidate))
+                cwd = candidate;
+        }
+        catch { /* Unavailable path stays unreported. */ }
+    }
+    const facts = configured ? input.describeConfigured?.(configured) : undefined;
+    if (configured && cwd) {
+        return managedSessionFields({ settings: configured, cwd, projectLabel: project?.label, configured: facts });
+    }
+    const fields = {};
+    if (configured) {
+        for (const key of SETTING_KEYS) {
+            if (configured[key])
+                fields[key] = { value: configured[key], provenance: 'configured' };
+        }
+        if (project?.label)
+            fields.projectLabel = { value: project.label, provenance: 'configured' };
+        applyConfiguredFacts(fields, facts);
+    }
+    else {
+        if (state.executionMode)
+            fields.executionMode = { value: state.executionMode, provenance: 'observed' };
+        if (project) {
+            fields.projectId = { value: project.id, provenance: 'observed' };
+            fields.projectLabel = { value: project.label, provenance: 'observed' };
+        }
+    }
+    if (cwd) {
+        fields.workingDirectory = { value: realpathSync(cwd), provenance: 'observed' };
+        Object.assign(fields, inspectGitEnvironment(cwd));
+    }
+    return fields;
+}
+/**
+ * Idempotent configuration for `createCanonManagedSessionHost`. Validates the
+ * owner's selection against the catalog, prepares the requested environment
+ * (a requested worktree that cannot be created fails instead of falling back)
+ * and saves the setup before the broker is acknowledged. A replayed request
+ * returns the saved setup; a conversation that already has a native session or
+ * a different confirmed setup keeps it.
+ */
+export function configureManagedSession(input) {
+    const { runtime } = input;
+    const selection = input.request.selection;
+    if (selection.mode !== 'configure' || input.catalog.managedSetup?.version !== 1)
+        throw new Error('This host does not support the requested setup.');
+    const existing = findManagedSessionState(input.runtimeId, input.request.conversationId, runtime);
+    if (existing?.codexManagedSetup) {
+        if (!savedSessionMatchesOwner(existing, input.ownerId ?? null, input.ownershipVersion))
+            throw new Error(`The saved ${runtime.label} setup belongs to a previous owner generation.`);
+        if (existing.codexManagedSetup.requestId !== input.request.requestId)
+            throw new Error(`This conversation already has a confirmed ${runtime.label} setup.`);
+        const settings = existing.codexManagedSetup.settings;
+        const environment = prepareConversationEnvironment({ agentId: input.agentId,
+            conversationId: input.request.conversationId, workspaceCwd: existing.baseCwd,
+            allowWorktrees: existing.executionMode === 'worktree' });
+        try {
+            if (environment.mode !== existing.executionMode)
+                throw new Error(`The saved ${runtime.label} execution environment is unavailable.`);
+            return { settings,
+                fields: managedSessionFields({ settings, cwd: environment.cwd,
+                    projectLabel: input.projects.find((project) => project.id === settings.projectId)?.label,
+                    configured: input.describeConfigured?.(settings) }),
+            };
+        }
+        finally {
+            releaseConversationEnvironment(environment);
+        }
+    }
+    if (hasSavedNativeSession(input.runtimeId, input.request.conversationId, runtime.resumeField))
+        throw new Error(`This conversation already has a native ${runtime.label} ${runtime.nativeSession}. Its settings are preserved.`);
+    const project = input.projects.find((entry) => entry.id === selection.projectId);
+    if (!project)
+        throw new Error('The selected project is unavailable on this host.');
+    const modelId = selection.modelId ?? input.catalog.defaults?.modelId;
+    const model = input.catalog.models?.find((entry) => entry.id === modelId);
+    if (modelId && !model)
+        throw new Error('The selected model is unavailable on this host.');
+    const reasoningEffort = selection.reasoningEffort ?? input.catalog.defaults?.reasoningEffort;
+    if (reasoningEffort && !(model?.reasoningEfforts?.length ? model.reasoningEfforts : input.catalog.reasoningEfforts ?? [])
+        .some((entry) => entry.id === reasoningEffort))
+        throw new Error('The selected thinking level is unavailable for this model.');
+    const permissionMode = selection.permissionMode ?? input.catalog.defaults?.permissionMode;
+    const executionMode = selection.executionMode ?? input.catalog.defaults?.executionMode;
+    if (!permissionMode || !input.catalog.permissionModes?.some((entry) => entry.id === permissionMode)
+        || !executionMode || !input.catalog.executionModes?.some((entry) => entry.id === executionMode))
+        throw new Error('The selected execution policy is unavailable on this host.');
+    if (input.isPermissionModeApplicable && !input.isPermissionModeApplicable(permissionMode, modelId))
+        throw new Error('The selected permission policy cannot be applied.');
+    const environment = prepareConversationEnvironment({ agentId: input.agentId,
+        conversationId: input.request.conversationId, workspaceCwd: project.cwd,
+        allowWorktrees: executionMode === 'worktree' });
+    try {
+        if (environment.mode !== executionMode)
+            throw new Error('The requested Git worktree could not be created. Select Project folder explicitly to use the base project.');
+        const settings = { projectId: project.id,
+            ...(modelId ? { modelId } : {}), ...(reasoningEffort ? { reasoningEffort } : {}),
+            permissionMode, executionMode };
+        const fields = managedSessionFields({ settings, cwd: environment.cwd, projectLabel: project.label,
+            configured: input.describeConfigured?.(settings) });
+        saveRuntimeSessionState(input.runtimeId, { conversationId: input.request.conversationId,
+            baseCwd: environment.baseCwd, executionMode: executionMode,
+            ...(input.ownerId ? { ownerId: input.ownerId } : {}),
+            ...(input.ownershipVersion !== undefined ? { ownershipVersion: input.ownershipVersion } : {}),
+            codexManagedSetup: { requestId: input.request.requestId, settings } });
+        return { settings, fields };
+    }
+    finally {
+        releaseConversationEnvironment(environment);
+    }
+}

package/dist/media.d.ts

@@ -82,6 +82,17 @@ export declare const MAX_CANON_MEDIA_BYTES: number;
 export declare const MAX_ANTHROPIC_IMAGE_RAW_BYTES: number;
 export declare const MAX_ANTHROPIC_REQUEST_BYTES = 32000000;
 export declare const DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES: number;
+/**
+ * The directory every materialized attachment of one conversation lands in
+ * (`<root>/<agent>/<conversation>/<message>/…`). A host that runs one native
+ * session per conversation can grant its runtime read access to exactly this
+ * directory instead of approving each downloaded file.
+ */
+export declare function conversationMediaCacheDir(input: {
+    agentId: string;
+    conversationId: string;
+    rootDir?: string;
+}): string;
 export declare function getMessageAttachments(message: Pick<CanonMessage, 'attachments'>): MediaAttachment[];
 export declare function materializeAttachment(attachment: MediaAttachment, options: MaterializeMediaOptions & {
     index?: number;

package/dist/media.js

@@ -82,6 +82,15 @@ function inferExtension(input) {
     }
     return '.bin';
 }
+/**
+ * The directory every materialized attachment of one conversation lands in
+ * (`<root>/<agent>/<conversation>/<message>/…`). A host that runs one native
+ * session per conversation can grant its runtime read access to exactly this
+ * directory instead of approving each downloaded file.
+ */
+export function conversationMediaCacheDir(input) {
+    return join(input.rootDir ?? DEFAULT_MEDIA_CACHE_DIR, sanitizeSegment(input.agentId, 'agent'), sanitizeSegment(input.conversationId, 'conversation'));
+}
 function buildCachePath(input) {
     const rootDir = input.rootDir ?? DEFAULT_MEDIA_CACHE_DIR;
     const extension = inferExtension({
@@ -93,7 +102,7 @@ function buildCachePath(input) {
         ? sanitizeDownloadFileName(input.attachment.fileName, fallbackName)
         : fallbackName;
     const fileName = extname(preferredName) ? preferredName : `${preferredName}${extension}`;
-    return join(rootDir, sanitizeSegment(input.agentId, 'agent'), sanitizeSegment(input.conversationId, 'conversation'), sanitizeSegment(input.messageId, 'message'), `${String(input.index).padStart(2, '0')}-${fileName}`);
+    return join(conversationMediaCacheDir({ agentId: input.agentId, conversationId: input.conversationId, rootDir }), sanitizeSegment(input.messageId, 'message'), `${String(input.index).padStart(2, '0')}-${fileName}`);
 }
 function ensureFetch(fetchImpl) {
     if (fetchImpl)

package/dist/types.d.ts

@@ -207,6 +207,26 @@ export interface MessageHandlerContext {
     provenance: CanonRuntimeProvenance;
     /** Compact structured Canon turn context for the latest inbound message in this handler batch. */
     turnContext: CanonTurnContextV2;
+    /**
+     * Each batched input's own shared-work references (the version it was
+     * about, `origin` and any selection), in batch order. Malformed references
+     * are dropped; an input with none is omitted.
+     */
+    artifactContexts: Array<{
+        messageId: string;
+        context: import('@canonmsg/core').ArtifactContext;
+    }>;
+    /**
+     * Shared work in this handler's conversation (chess, forms, images): exactly
+     * `CanonClient.artifacts(conversationId)`. Changes are made against the state
+     * this agent last read or wrote (across turns), so a person's newer edit is
+     * reported as a `CanonArtifactError` conflict instead of being overwritten:
+     * `describe()` before `update()` (or pass `basedOnRevisionId`); with no read
+     * yet, `update()` rejects with `NOT_READ`. Arrival reads nothing on the
+     * handler's behalf. Dev-only preview; other environments reject with
+     * `ARTIFACTS_UNAVAILABLE`.
+     */
+    readonly artifacts: import('@canonmsg/core').CanonConversationArtifacts;
     /** Runtime turn mode requested by the sender for this inbound turn, if any. */
     requestedTurnMode: string | null;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "11.1.1",
+  "version": "11.2.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "node": ">=22.22.3"
   },
   "dependencies": {
-    "@canonmsg/core": "^13.2.0"
+    "@canonmsg/core": "^13.3.0"
   },
   "repository": {
     "type": "git",