@canonmsg/agent-sdk 12.0.0 → 12.1.0

package/dist/internal/backend-contracts/workSessions.d.ts

@@ -1,205 +0,0 @@
-/** Private owner/operator workflow. None of this catalog belongs in public runtime descriptors. */
-export declare const WORK_SESSION_SCHEMA: "canon.work-sessions.v1";
-export declare const WORK_SESSION_LEASE_MS = 90000;
-export declare const WORK_SESSION_REQUEST_TTL_MS: number;
-export interface WorkSessionChoice {
-    id: string;
-    label: string;
-    description?: string;
-}
-export interface WorkSessionModelChoice extends WorkSessionChoice {
-    reasoningEfforts?: WorkSessionChoice[];
-    defaultReasoningEffort?: string;
-}
-export interface WorkSessionSettings {
-    projectId?: string;
-    modelId?: string;
-    reasoningEffort?: string;
-    permissionMode?: string;
-    executionMode?: string;
-}
-export type WorkSessionSelection = ({
-    mode: 'create';
-    projectId: string;
-} & Omit<WorkSessionSettings, 'projectId'>) | ({
-    mode: 'configure';
-    projectId: string;
-} & Omit<WorkSessionSettings, 'projectId'>) | {
-    mode: 'attach';
-    sessionId: string;
-};
-export interface WorkSessionLoadedSession {
-    id: string;
-    title: string;
-    status: 'idle' | 'running';
-    settings: WorkSessionSettings;
-    projectLabel?: string;
-    modelLabel?: string;
-}
-export interface WorkSessionCatalog {
-    revision: string;
-    provider: string;
-    canCreate: boolean;
-    canAttach: boolean;
-    projects: WorkSessionChoice[];
-    models?: WorkSessionModelChoice[];
-    reasoningEfforts?: WorkSessionChoice[];
-    permissionModes?: WorkSessionChoice[];
-    executionModes?: WorkSessionChoice[];
-    defaults?: WorkSessionSettings;
-    sessions: WorkSessionLoadedSession[];
-    /** Opt-in extension. Older runtimes may still create or attach native sessions. */
-    managedSetup?: {
-        version: 1;
-    };
-}
-export interface WorkSessionRuntimeIdentity {
-    hostId: string;
-    runtimeEpoch: string;
-}
-export interface WorkSessionRuntimeLease extends WorkSessionRuntimeIdentity {
-    /** Agent-only fencing credential. Never expose in the owner catalog or request status. */
-    leaseToken: string;
-    expiresAt: number;
-}
-export interface WorkSessionRuntimeRegistration extends WorkSessionRuntimeIdentity {
-    displayName: string;
-    catalog: WorkSessionCatalog;
-}
-interface WorkSessionBindingBase {
-    workSessionId: string;
-    conversationId: string;
-    hostId: string;
-    provider: string;
-    settings: WorkSessionSettings;
-    createdAt: number;
-}
-export type WorkSessionBinding = (WorkSessionBindingBase & {
-    kind?: 'native';
-    nativeSessionId: string;
-}) | (WorkSessionBindingBase & {
-    kind: 'managed';
-    nativeSessionId?: never;
-});
-export interface WorkSessionRuntimeState {
-    ownerId: string;
-    lease: WorkSessionRuntimeLease;
-    bindings: WorkSessionBinding[];
-}
-export interface WorkSessionCatalogResult {
-    status: 'available' | 'offline' | 'unavailable';
-    agentId: string;
-    hostId?: string;
-    runtimeEpoch?: string;
-    displayName?: string;
-    expiresAt?: number;
-    catalog?: WorkSessionCatalog;
-    bindings: WorkSessionBinding[];
-}
-export interface RequestWorkSessionInput extends WorkSessionRuntimeIdentity {
-    agentId: string;
-    conversationId: string;
-    requestId: string;
-    catalogRevision: string;
-    selection: WorkSessionSelection;
-}
-export type WorkSessionRequestStatus = 'pending' | 'claimed' | 'attached' | 'configured' | 'failed' | 'uncertain' | 'expired';
-export interface WorkSessionRequest extends RequestWorkSessionInput {
-    schema: typeof WORK_SESSION_SCHEMA;
-    requestedBy: string;
-    status: WorkSessionRequestStatus;
-    createdAt: number;
-    updatedAt: number;
-    expiresAt: number;
-    binding?: WorkSessionBinding;
-    error?: {
-        code: string;
-        message: string;
-    };
-}
-export type WorkSessionCompletion = {
-    status: 'attached';
-    nativeSessionId: string;
-    settings: WorkSessionSettings;
-} | {
-    status: 'configured';
-    settings: WorkSessionSettings;
-} | {
-    status: 'failed' | 'uncertain';
-    error: {
-        code: string;
-        message: string;
-    };
-};
-export type WorkSessionRuntimeAuth = Pick<WorkSessionRuntimeLease, 'hostId' | 'runtimeEpoch' | 'leaseToken'>;
-export interface WorkSessionClaimInput extends WorkSessionRuntimeAuth {
-    requestId?: string;
-}
-export interface WorkSessionClaimResult {
-    request: WorkSessionRequest | null;
-    /** Previously claimed: reconcile the durable host journal, never blindly execute again. */
-    replayed: boolean;
-}
-export interface CompleteWorkSessionInput extends WorkSessionRuntimeAuth {
-    requestId: string;
-    result: WorkSessionCompletion;
-}
-export interface WorkSessionHeartbeatInput extends WorkSessionRuntimeAuth {
-    catalog?: WorkSessionCatalog;
-}
-export interface ReleaseWorkSessionBindingInput extends WorkSessionRuntimeAuth {
-    conversationId: string;
-    workSessionId: string;
-}
-export interface ResolveWorkSessionRequestInput {
-    agentId: string;
-    requestId: string;
-}
-export interface GetWorkSessionRequestInput {
-    agentId: string;
-    /** Exactly one selector. Conversation lookup recovers the latest operation after reload. */
-    requestId?: string;
-    conversationId?: string;
-}
-export interface GetWorkSessionDetailsInput {
-    agentId: string;
-    conversationId: string;
-}
-export type WorkSessionDetailField = keyof WorkSessionSettings | 'projectLabel' | 'workingDirectory' | 'branch' | 'worktreePath' | 'sandbox' | 'approvalPolicy' | 'nativeThreadBehavior';
-export interface WorkSessionDetailValue {
-    value: string;
-    provenance: 'configured' | 'observed';
-}
-export type WorkSessionDetailFields = Partial<Record<WorkSessionDetailField, WorkSessionDetailValue>>;
-/** Host supplied private facts. The server stamps reportedAt and checks the current lease and membership. */
-export interface WorkSessionReportInput extends WorkSessionRuntimeAuth {
-    conversationId: string;
-    workSessionId?: string;
-    setupState?: 'configured' | 'attached';
-    fields: WorkSessionDetailFields;
-}
-export interface WorkSessionDetailsResult {
-    status: 'available' | 'offline' | 'unavailable';
-    agentId: string;
-    conversationId: string;
-    setupState: 'unconfigured' | 'pending' | 'configured' | 'attached' | 'failed' | 'uncertain';
-    hostId?: string;
-    displayName?: string;
-    expiresAt?: number;
-    binding?: WorkSessionBinding;
-    selection?: WorkSessionSelection;
-    fields: WorkSessionDetailFields;
-    reportedAt?: number;
-}
-export declare function workSessionId(value: unknown, label?: string): string;
-export declare function parseWorkSessionSettings(value: unknown): WorkSessionSettings;
-export declare function parseWorkSessionCatalog(value: unknown): WorkSessionCatalog;
-export declare function parseWorkSessionSelection(value: unknown): WorkSessionSelection;
-export declare function assertWorkSessionSelectionAvailable(selection: WorkSessionSelection, catalog: WorkSessionCatalog): void;
-export declare function parseWorkSessionRuntimeRegistration(value: unknown): WorkSessionRuntimeRegistration;
-export declare function parseWorkSessionRuntimeAuth(value: unknown, extraKeys?: string[]): WorkSessionRuntimeAuth;
-export declare function parseRequestWorkSessionInput(value: unknown): RequestWorkSessionInput;
-export declare function parseWorkSessionCompletion(value: unknown): WorkSessionCompletion;
-export declare function parseWorkSessionDetailFields(value: unknown): WorkSessionDetailFields;
-export declare function parseWorkSessionReportInput(value: unknown): WorkSessionReportInput;
-export {};

package/dist/internal/core/agent-resolver.d.ts

@@ -1,49 +0,0 @@
-/**
- * Unified agent resolution — resolves Canon agent credentials from
- * environment variables or ~/.canon/agents.json profiles.
- *
- * Used by the Claude Code plugin (host.ts, server.ts) and available
- * for any future agent integration.
- *
- * Resolution order:
- * 1. CANON_API_KEY env var (highest priority, no lock)
- * 2. CANON_AGENT env var (named profile with lock)
- * 3. Auto-select from profiles (first unlocked, with lock)
- */
-import { type ProfileLockHandle } from './agent-profiles.js';
-import type { CanonEnvironmentId } from '../backend-contracts/index.js';
-import type { AgentClientType } from './types.js';
-export interface ResolvedAgent {
-    apiKey: string;
-    agentId?: string;
-    profile: string | null;
-    agentName?: string;
-    clientType?: AgentClientType;
-    environmentId: CanonEnvironmentId;
-    baseUrl: string;
-    streamUrl: string;
-    rtdbUrl: string;
-    firebaseApiKey: string;
-    lockHandle?: ProfileLockHandle;
-}
-export declare function verifyResolvedAgentEnvironment(resolved: ResolvedAgent): Promise<void>;
-/** Get the currently locked profile name (for cleanup on shutdown). */
-export declare function getActiveProfile(): string | null;
-export declare function getActiveProfileLock(): ProfileLockHandle | null;
-export declare function resolveCanonProfile(name: string, opts?: {
-    logPrefix?: string;
-    lock?: boolean;
-    expectedClientType?: AgentClientType;
-}): ResolvedAgent;
-/**
- * Resolve Canon agent credentials.
- *
- * @param opts.logPrefix - Log prefix for console messages (default: '[canon]')
- * @returns Resolved agent with API key, optional agentId, and profile name
- * @throws Error if no agent can be resolved
- */
-export declare function resolveCanonAgent(opts?: {
-    logPrefix?: string;
-    expectedClientType?: AgentClientType;
-    lock?: boolean;
-}): ResolvedAgent;

package/dist/internal/core/agent-session.d.ts

@@ -1,12 +0,0 @@
-import type { AgentRuntime, AgentSessionSnapshot, SessionState } from './types.js';
-import type { TurnState } from './turn-protocol.js';
-export interface BuildAgentSessionSnapshotInput {
-    conversationId: string;
-    agentId: string;
-    runtime?: AgentRuntime | null;
-    sessionState?: SessionState | null;
-    turnState?: TurnState | null;
-    lastHeartbeatAt?: number | null;
-    updatedAt?: number | null;
-}
-export declare function buildAgentSessionSnapshot(input: BuildAgentSessionSnapshotInput): AgentSessionSnapshot;

package/dist/internal/core/artifacts.d.ts

@@ -1,262 +0,0 @@
-import { type ArtifactActionValue, type ArtifactAsset, type ArtifactCommandBody, type ArtifactCreateAction, type ArtifactDomainOutcome, type ArtifactFormValue, type ArtifactGenerateImageAction, type ArtifactKind, type ArtifactSnapshot, type ArtifactUpdateAction as ArtifactUpdateActionContract, type MediaAttachment } from '../backend-contracts/index.js';
-import { ArtifactRejectedError, type ArtifactClient, type ArtifactImageClient, type ArtifactImageVariantView, type ArtifactImageView, type ArtifactLibrary, type ArtifactPrincipalView, type ArtifactView } from '../endpoint/index.js';
-import type { CanonMessage } from './types.js';
-import type { CanonClient } from './client.js';
-/** Form input: numeric text ("12.50") for number fields and "true"/"false" for checkboxes is converted. */
-export type ArtifactInputValue = ArtifactActionValue;
-/** An `update` action: the shared contract's `ArtifactUpdateAction`. */
-export type ArtifactUpdateAction = ArtifactUpdateActionContract;
-/**
- * A `create` input: the shared contract's flat `ArtifactCreateAction`.
- * `playAs` seats this agent; `opponent` (a participant ID) takes the other
- * seat. No `playAs` makes an open board.
- */
-export type ArtifactCreateInput = ArtifactCreateAction;
-export interface ArtifactListItem {
-    artifactId: string;
-    kind: ArtifactKind;
-    title: string;
-    summary: string;
-    archived: boolean;
-    updatedAt: string;
-}
-/** `unavailable` includes `NO_DEFINITION` work and `ARTIFACT_LOADING` work whose long history is still replaying (list again shortly). */
-export interface ArtifactList {
-    items: ArtifactListItem[];
-    unavailable: ArtifactLibrary['unavailable'];
-}
-/**
- * `delivery: 'queued'`: the durable outbox is still delivering the change and
- * the view is a prediction; do not resend. (Not `status`: a chess view's
- * `status` is the game's.) `alreadyApplied`: this identical change was already
- * made for the same request; nothing new was applied. The view shows the work
- * as it is now, with what others changed, but it does not move the base: the
- * next change is still judged against what this client saw before.
- */
-export type ArtifactWriteView<V extends ArtifactView = ArtifactView> = V & {
-    delivery: 'accepted' | 'queued';
-    alreadyApplied?: true;
-};
-export type ArtifactUpdateResult = ArtifactWriteView & {
-    addedRowIds?: string[];
-};
-/** The shared contract's generate action (`from` 'current' is the work's current version) plus call options. */
-export interface ArtifactGenerateImageInput extends ArtifactGenerateImageAction {
-    /** Repeating a call with the same key and input collects the same generation. */
-    requestKey?: string;
-    /** Cancels the wait. A job already submitted keeps running: the result is `generating`. */
-    signal?: AbortSignal;
-    timeoutMs?: number;
-}
-export type ArtifactGenerateImageResult = {
-    status: 'added';
-    view: ArtifactWriteView<ArtifactImageView>;
-    variant: ArtifactImageVariantView;
-    attachment: MediaAttachment;
-} | {
-    status: 'generating';
-    requestId: string;
-};
-/** Exactly one source: a local JPEG/PNG file, a retained Canon upload, or an image attached to a message. */
-export interface ArtifactAddImageInput {
-    label: string;
-    prompt?: string;
-    sourceVariantId?: string;
-    /** Default true: the version becomes current (an image the work already holds is made current again). */
-    select?: boolean;
-    filePath?: string;
-    assetId?: string;
-    messageId?: string;
-    /** Index into the message's attachments; defaults to its first image. */
-    attachmentIndex?: number;
-    /**
-     * With `messageId` and no `attachmentIndex`: the message whose image is used
-     * when `messageId`'s message has none (for example the message it replies to).
-     */
-    fallbackMessageId?: string;
-    requestKey?: string;
-    signal?: AbortSignal;
-}
-export interface ArtifactAddImageResult {
-    view: ArtifactWriteView<ArtifactImageView>;
-    variant: ArtifactImageVariantView;
-}
-export interface ArtifactConflictView {
-    path: string[];
-    label: string;
-    expected: ArtifactFormValue;
-    current: ArtifactFormValue;
-    currentBy?: ArtifactPrincipalView;
-}
-export type CanonArtifactErrorCode = ArtifactRejectedError['code'] | 'NOT_READ' | 'NOT_FOUND' | 'MESSAGE_NOT_FOUND' | 'INVALID_INPUT';
-/**
- * A change the shared rules (or local input checks) refused. Nothing new was
- * accepted. For a rejection evaluated against the current work, `view` is that
- * fresh state (with `changesSinceLastView`). Only a `CONFLICT` makes it the
- * new last-seen base (decide again); any other rejection leaves the base where
- * it was. Form conflicts are listed in `conflicts`.
- */
-export declare class CanonArtifactError extends Error {
-    readonly code: CanonArtifactErrorCode;
-    readonly outcome?: ArtifactDomainOutcome;
-    readonly conflicts?: ArtifactConflictView[];
-    readonly view?: ArtifactView;
-    constructor(message: string, options: {
-        code: CanonArtifactErrorCode;
-        outcome?: ArtifactDomainOutcome;
-        conflicts?: ArtifactConflictView[];
-        view?: ArtifactView;
-        cause?: unknown;
-    });
-}
-/** Shared work in one conversation (SDK `ctx.artifacts`). */
-export interface CanonConversationArtifacts {
-    readonly conversationId: string;
-    list(): Promise<ArtifactList>;
-    /** The current state (records it as last seen), or an earlier revision (read-only, not recorded). */
-    describe(artifactId: string, options?: {
-        revisionId?: string;
-    }): Promise<ArtifactView>;
-    /**
-     * One viewer-relative line about the current state. Chess and image work
-     * become the base of the next change (the line shows enough to act on), but
-     * not "read": the next `describe` still lists the changes since the last
-     * read or write. A form never becomes the base here (its values are not in
-     * the line), so a change to it still needs a read.
-     */
-    summarize(artifactId: string, options?: {
-        signal?: AbortSignal;
-    }): Promise<string>;
-    create(input: ArtifactCreateInput, options?: {
-        requestKey?: string;
-    }): Promise<ArtifactWriteView>;
-    update(artifactId: string, action: ArtifactUpdateAction, options?: {
-        basedOnRevisionId?: string;
-        requestKey?: string;
-    }): Promise<ArtifactUpdateResult>;
-    generateImage(artifactId: string, input: ArtifactGenerateImageInput): Promise<ArtifactGenerateImageResult>;
-    addImage(artifactId: string, input: ArtifactAddImageInput): Promise<ArtifactAddImageResult>;
-    getAsset(artifactId: string, assetId: string): Promise<ArtifactAsset>;
-    /** Live views of one work (each recorded as last seen). */
-    observe(artifactId: string, listener: (view: ArtifactView) => void, onError?: (error: unknown) => void): () => void;
-    observeList(listener: (list: ArtifactList) => void, onError?: (error: unknown) => void): () => void;
-}
-/** Declared MIME types an image version may have (JPEG or PNG), lower case. */
-export declare const ARTIFACT_IMAGE_MIME_TYPES: ReadonlySet<string>;
-/** The image type from the bytes themselves (PNG or JPEG signature); anything else is undefined. */
-export declare function sniffArtifactImageType(bytes: Uint8Array): 'image/jpeg' | 'image/png' | undefined;
-type ArtifactIntent = {
-    commandId: string;
-    command: ArtifactCommandBody;
-    addedRowIds: string[];
-    resultRevisionId: string;
-}
-/** `attempts` rejected sends so far; the next deliberate repeat uses a fresh command ID. */
- | {
-    commandId: string;
-    rejected: true;
-    attempts: number;
-};
-/**
- * Per-client memory: per conversation's work, the base of the next change and
- * the last snapshot shown in full (what changesSinceLastView is relative to);
- * keyed intents; and participant names. Keys are local only, never sent.
- */
-export declare class ArtifactMemory {
-    private readonly seen;
-    private ticks;
-    private readonly rooms;
-    /** Keyed changes this client issued: what each one led to. */
-    private readonly intents;
-    /** Generations still running, by what was asked (not by turn): a later call with the same arguments collects them. */
-    private readonly generating;
-    /** Terminal generation failures per request and arguments: a repeat starts a fresh generation. */
-    private readonly generationFailures;
-    intent(key: string): ArtifactIntent | undefined;
-    rememberIntent(key: string, intent: ArtifactIntent): void;
-    pendingGeneration(key: string): string | undefined;
-    /** `undefined` once the generation was collected or failed. */
-    rememberGeneration(key: string, requestId: string | undefined): void;
-    generationAttempts(key: string): number;
-    recordGenerationFailure(key: string): void;
-    /** The base of the next change. */
-    lastSeen(conversationId: string, artifactId: string): ArtifactSnapshot | undefined;
-    /** The last full view (read, write, conflict or observation): what diffs are relative to. */
-    lastShown(conversationId: string, artifactId: string): ArtifactSnapshot | undefined;
-    /** Taken when an operation begins; pass it to `remember` with the operation's result. */
-    mark(): number;
-    /**
-     * Record what this client last showed of the work. A newer sequence always
-     * wins. An older one wins only for an operation (`since` = its `mark()`)
-     * that began after the last record: a fresh read then replaces a queued
-     * write's prediction that never landed, or a log that was replaced, while a
-     * slow read that raced a newer write cannot regress the base. Observer
-     * deliveries (no `since`) never move back. `baseOnly` (a prompt summary)
-     * moves the base but keeps the diff baseline.
-     */
-    remember(snapshot: ArtifactSnapshot, since?: number, options?: {
-        baseOnly?: boolean;
-    }): void;
-    room(conversationId: string): {
-        names: Map<string, string>;
-        refreshedAt: number;
-    };
-    rememberNames(conversationId: string, names: Record<string, string | null | undefined>): void;
-}
-/** What a room object needs from its CanonClient (injected for tests). */
-export interface ArtifactRoomHost {
-    artifacts(): Promise<ArtifactClient>;
-    images(): Promise<ArtifactImageClient>;
-    principalId(): Promise<string>;
-    /** Upload a local image as a prepared (not yet sent) Canon attachment. */
-    prepareImageUpload(input: {
-        conversationId: string;
-        attachmentId: string;
-        source: string;
-        mimeType: string;
-        sizeBytes: number;
-        fileName: string;
-        signal?: AbortSignal;
-    }): Promise<MediaAttachment>;
-    getMessage(conversationId: string, messageId: string): Promise<CanonMessage | null>;
-    /** Recent messages, for participant names. */
-    recentMessages(conversationId: string): Promise<CanonMessage[]>;
-    memory: ArtifactMemory;
-    now?: () => number;
-}
-/** Keyed identity derivation (the endpoint's per-installation secret): what `artifactCommandId` and `artifactRequestUuid` need. */
-export type ArtifactIdDerivation = Pick<ArtifactClient, 'deriveCommandId' | 'deriveRequestId'>;
-/**
- * Command ID for one deliberate change: the same principal, request (turn)
- * and action give the same command, so a repeated call never applies twice.
- * The principal keeps agents that handle the same message apart.
- * `baseRevisionId` distinguishes a deliberate repeat after the work moved on;
- * `attempt` a repeat after a rejected send (whose ID keeps its rejection).
- * Keyed with this installation's secret: the server can never test a guess of
- * the action against it.
- */
-export declare function artifactCommandId(ids: Pick<ArtifactIdDerivation, 'deriveCommandId'>, parts: {
-    conversationId: string;
-    artifactId: string;
-    principalId: string;
-    requestKey: string;
-    action: unknown;
-    baseRevisionId?: string;
-    attempt?: number;
-}): Promise<string>;
-/** A stable, keyed, RFC 4122-shaped ID (image request and upload attachment IDs) for `material`. */
-export declare function artifactRequestUuid(ids: Pick<ArtifactIdDerivation, 'deriveRequestId'>, material: unknown[]): Promise<string>;
-export declare function createConversationArtifacts(host: ArtifactRoomHost, conversationId: string): CanonConversationArtifacts;
-/**
- * One-line summaries "as of message arrival" for the work a message reports
- * activity on (`origin: 'activity'`), keyed by artifact ID, for the prompt.
- * Lenient: a malformed context, a failed read, the timeout or `signal` omits
- * the line (a read cancelled by `signal` records nothing). `names` (for
- * example the sender) seeds participant names.
- */
-export declare function summarizeArtifactReferences(client: Pick<CanonClient, 'artifacts'> & Partial<Pick<CanonClient, 'rememberParticipantNames'>>, conversationId: string, context: unknown, options?: {
-    timeoutMs?: number;
-    names?: Record<string, string | null | undefined>;
-    signal?: AbortSignal;
-}): Promise<Record<string, string>>;
-export {};