@canonmsg/agent-sdk 11.2.0 → 12.0.0

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

@@ -0,0 +1,205 @@
+/** 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-profiles.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared agent profile management — loading, locking, and resolution.
+ * Used by both host.ts and server.ts.
+ */
+import type { CanonEnvironmentId } from '../backend-contracts/index.js';
+import type { AgentClientType } from './types.js';
+import { type CanonRuntimeConnectionOptions } from './runtime-endpoints.js';
+export interface AgentProfileInput {
+    apiKey: string;
+    agentId: string;
+    agentName: string;
+    registeredAt: string;
+    environmentId: CanonEnvironmentId;
+    baseUrl: string;
+    streamUrl: string;
+    rtdbUrl: string;
+    firebaseApiKey: string;
+    clientType?: AgentClientType;
+    runtimeId?: string;
+}
+export interface AgentProfile extends AgentProfileInput {
+    baseUrl: string;
+    streamUrl: string;
+    rtdbUrl: string;
+    firebaseApiKey: string;
+}
+export interface ProfileLockHandle {
+    profile: string;
+    pid: number;
+    token: string;
+    release(): void;
+}
+export declare const CANON_DIR: string;
+export declare const AGENTS_PATH: string;
+export declare const LOCKS_DIR: string;
+export declare const PENDING_REGISTRATIONS_PATH: string;
+/** `home` names the Canon home explicitly; without it, CANON_HOME as read at import applies. */
+export declare function loadProfiles(home?: string): Record<string, AgentProfile>;
+export declare function saveProfiles(profiles: Record<string, AgentProfile>, home?: string): void;
+export declare function upsertAgentProfile(name: string, profile: AgentProfileInput): Record<string, AgentProfile>;
+export declare function isProcessAlive(pid: number): boolean;
+export declare function isProfileLocked(profile: string, home?: string): {
+    locked: boolean;
+    pid?: number;
+};
+export declare function acquireLock(profile: string, home?: string): ProfileLockHandle;
+export declare function releaseLock(profile: string, token?: string, home?: string): void;
+export interface PendingRegistration {
+    profile: string;
+    clientType?: AgentClientType;
+    localRegistrationId: string;
+    environmentId: CanonEnvironmentId;
+    baseUrl: string;
+    streamUrl: string;
+    rtdbUrl: string;
+    firebaseApiKey: string;
+    requestId?: string;
+    pollToken?: string;
+    ownerPhone?: string;
+    requestedAgentId?: string;
+    credentialAgentId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function loadPendingRegistrations(): Record<string, PendingRegistration>;
+export declare function savePendingRegistrations(pending: Record<string, PendingRegistration>): void;
+export declare function getOrCreatePendingRegistration(profile: string, clientType?: AgentClientType, connectionOptions?: CanonRuntimeConnectionOptions): PendingRegistration;
+export declare function updatePendingRegistration(profile: string, patch: Partial<Pick<PendingRegistration, 'requestId' | 'pollToken' | 'clientType'>>): PendingRegistration;
+export declare function clearPendingRegistration(profile: string): void;

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

@@ -0,0 +1,49 @@
+/**
+ * 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

@@ -0,0 +1,12 @@
+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/approval-format.d.ts

@@ -0,0 +1,26 @@
+import type { ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalNativeRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, SessionRule } from './approval-types.js';
+import type { CanonUnifiedDiff } from './types.js';
+export declare function generateApprovalId(): string;
+export declare function redactSecrets(text: string, patterns: string[]): string;
+export declare function buildApprovalRequest(approvalId: string, toolName: string, toolInput: Record<string, unknown>, opts: {
+    riskLevel?: 'normal' | 'destructive';
+    risk?: ApprovalRisk;
+    category?: ApprovalRequestCategory;
+    responseUserId?: string;
+    runtimeId?: string;
+    turnId?: string;
+    native?: ApprovalNativeRequestMetadata;
+    toolSummary?: string;
+    details?: ApprovalRequestDetail[];
+    diff?: CanonUnifiedDiff;
+    expiresAt: string;
+    redactPatterns?: string[];
+}): {
+    text: string;
+    metadata: ApprovalRequestMetadata;
+};
+export declare function buildApprovalReply(approvalId: string, decision: 'allow' | 'deny', sessionRule?: SessionRule): {
+    text: string;
+    metadata: ApprovalReplyMetadata;
+};
+export declare function buildApprovalOutcome(approvalId: string, toolName: string, toolSummary: string, decision: 'allow' | 'deny', reason: 'replied' | 'timeout' | 'session-rule'): string;

package/dist/internal/core/approval-manager.d.ts

@@ -0,0 +1,43 @@
+import type { CanonClient } from './client.js';
+import type { CanonUnifiedDiff } from './types.js';
+import type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalResult, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk } from './approval-types.js';
+import { RuntimeRequestManager, type RuntimeRequestOptions } from './runtime-request-manager.js';
+interface ApprovalRequestOpts {
+    riskLevel?: 'normal' | 'destructive';
+    risk?: ApprovalRisk;
+    category?: ApprovalRequestCategory;
+    runtimeId?: string;
+    turnId?: string;
+    native?: ApprovalNativeRequestMetadata;
+    toolSummary?: string;
+    details?: ApprovalRequestDetail[];
+    /** File-change preview rendered inline on the approval card (size-disciplined automatically). */
+    diff?: CanonUnifiedDiff;
+    ignoreSessionRules?: boolean;
+    allowSessionRule?: boolean;
+    /** Human conversation member who triggered this turn and should answer. */
+    responseUserId?: string;
+}
+/**
+ * Platform-agnostic approval protocol for Canon.
+ *
+ * Now a thin `RuntimeRequestManager` subclass: the pending map, deadline timers,
+ * the hybrid poll-plus-push loop, and cancellation live in the generalized
+ * engine; approval-specific behaviour (session-rule fast path, redacted request
+ * metadata, owner-authored outcome messages, and session-rule storage) is
+ * expressed as a single `KindDescriptor`. Behaviour is preserved verbatim.
+ */
+export declare class ApprovalManager extends RuntimeRequestManager {
+    private config;
+    constructor(client: CanonClient, agentId: string, ownerId: string, config?: Partial<ApprovalConfig>);
+    /**
+     * Request approval for a tool call.
+     *
+     * 1. Checks session rules — may resolve immediately.
+     * 2. Sends a message with approval card metadata.
+     * 3. Waits for the owner's reply (or timeout).
+     */
+    requestApproval(conversationId: string, toolName: string, toolInput: Record<string, unknown>, opts?: ApprovalRequestOpts, runtimeOptions?: RuntimeRequestOptions): Promise<ApprovalResult>;
+    private buildApprovalDescriptor;
+}
+export {};

package/dist/internal/core/approval-types.d.ts

@@ -0,0 +1,74 @@
+import { type VerbNativeMetadata } from '../backend-contracts/index.js';
+import type { CanonUnifiedDiff } from './types.js';
+export interface ApprovalRequestMetadata {
+    type: 'approval_request';
+    approvalId: string;
+    /** Canon user who should answer this card. UI hint only; reply APIs still enforce authorization. */
+    responseUserId?: string;
+    toolName: string;
+    /** Pre-computed, redacted summary — raw toolInput is never stored */
+    toolSummary: string;
+    /** Broad action family for richer Canon approval cards. */
+    category?: ApprovalRequestCategory;
+    /** Preferred v2 risk signal. `riskLevel` remains for older clients. */
+    risk?: ApprovalRisk;
+    riskLevel?: 'normal' | 'destructive';
+    runtimeId?: string;
+    turnId?: string;
+    /** Native runtime correlation handle. Canon stores this opaquely for plugins/SDK bridges. */
+    native?: ApprovalNativeRequestMetadata;
+    /** Redacted, normalized details. Raw tool input must not be stored here. */
+    details?: ApprovalRequestDetail[];
+    /**
+     * File-change preview for file approvals — full unified diff so the owner
+     * can review the change inline before approving, like native habitats.
+     * Size-disciplined via truncateUnifiedDiff.
+     */
+    diff?: CanonUnifiedDiff;
+    /** Whether the responder may create a rule that applies to later turns. */
+    allowSessionRule?: boolean;
+    expiresAt: string;
+}
+export interface ApprovalOutcomeMetadata {
+    type: 'approval_outcome';
+    approvalId?: string;
+    decision?: 'allow' | 'deny';
+    reason?: 'replied' | 'timeout' | 'session-rule';
+}
+export interface ApprovalReplyMetadata {
+    type: 'approval_reply';
+    approvalId: string;
+    decision: 'allow' | 'deny';
+    sessionRule?: SessionRule;
+}
+export type ApprovalRequestCategory = 'command' | 'file' | 'network' | 'browser' | 'mcp' | 'plugin' | 'canon' | 'tool';
+export type ApprovalRisk = 'low' | 'normal' | 'high' | 'destructive';
+export interface ApprovalRequestDetail {
+    label: string;
+    value: string;
+    monospace?: boolean;
+}
+export type ApprovalNativeRequestMetadata = VerbNativeMetadata;
+export interface SessionRule {
+    type: 'approve-all' | 'approve-tool' | 'deny-tool';
+    /** Tool name pattern (regex) — only for approve-tool/deny-tool */
+    toolPattern?: string;
+    /** When this rule expires (ISO 8601), null = session lifetime */
+    expiresAt?: string | null;
+}
+export interface ApprovalResult {
+    decision: 'allow' | 'deny';
+    sessionRule?: SessionRule;
+    /** Canon-authenticated human who submitted this decision. */
+    respondedBy?: string;
+}
+export interface ApprovalConfig {
+    enabled: boolean;
+    timeoutSeconds: number;
+    defaultOnTimeout: 'deny' | 'ask';
+    redactPatterns: string[];
+}
+export declare const DEFAULT_APPROVAL_CONFIG: ApprovalConfig;
+export declare function parseSessionRule(value: unknown): SessionRule | null;
+export declare function parseApprovalReplyMetadata(value: unknown): ApprovalReplyMetadata | null;
+export declare function parseApprovalRequestMetadata(value: unknown): ApprovalRequestMetadata | null;