@siduri-x/core 1.0.5 → 1.0.7

package/dist/capability.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Resolves the action policy secret key.
+ * In production (NODE_ENV=production), ACTION_POLICY_SECRET is required.
+ * In local/development environments, if no secret is provided via environment
+ * or options, generates an ephemeral cryptographically strong secret per-process,
+ * avoiding shared hardcoded fallback secrets.
+ */
+export declare function getOrGenerateLocalActionPolicySecret(provided?: string): string;
+import { ActionRiskLevel, ActionLifecycleState, ActionAuditEvent, ActionPolicyDecision } from './action';
+export interface AuthorizationCapability {
+    executionId: string;
+    actionId: string;
+    toolName: string;
+    providerId: string;
+    parametersHash: string;
+    companionId: string;
+    actorId?: string;
+    sessionId?: string;
+    channel?: string;
+    correlationId?: string;
+    riskLevel: ActionRiskLevel;
+    issuedAt: string;
+    expiresAt: string;
+    allowed: true;
+    signature: string;
+}
+export interface PersistentExecutionRecord {
+    executionId: string;
+    actionId: string;
+    toolName: string;
+    providerId: string;
+    parametersHash: string;
+    lifecycle: ActionLifecycleState;
+    decision?: ActionPolicyDecision;
+    result?: unknown;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ActionStore {
+    reserveExecution(record: PersistentExecutionRecord): Promise<boolean>;
+    updateExecution(record: PersistentExecutionRecord): Promise<void>;
+    getExecution(executionId: string): Promise<PersistentExecutionRecord | undefined>;
+    saveApproval(executionId: string, approverActorId: string, reason?: string): Promise<void>;
+    isActionApproved(executionId: string): Promise<boolean>;
+    appendAudit(event: ActionAuditEvent): Promise<void>;
+    getAuditLog(executionId?: string): Promise<ActionAuditEvent[]>;
+}
+export declare class InMemoryActionStore implements ActionStore {
+    private readonly executions;
+    private readonly approvals;
+    private readonly auditLog;
+    private lastAuditHash;
+    reserveExecution(record: PersistentExecutionRecord): Promise<boolean>;
+    updateExecution(record: PersistentExecutionRecord): Promise<void>;
+    getExecution(executionId: string): Promise<PersistentExecutionRecord | undefined>;
+    saveApproval(executionId: string, approverActorId: string, reason?: string): Promise<void>;
+    isActionApproved(executionId: string): Promise<boolean>;
+    appendAudit(event: ActionAuditEvent): Promise<void>;
+    getAuditLog(executionId?: string): Promise<ActionAuditEvent[]>;
+}
+export declare function canonicalizeJson(obj: unknown): string;
+export declare function computeParametersHash(params: unknown): string;
+export declare function signCapabilityPayload(payload: Record<string, unknown>, secretKey?: string): string;
+export declare function verifyCapabilitySignature(capability: AuthorizationCapability, secretKey?: string): boolean;

package/dist/capability.js

@@ -0,0 +1,157 @@
+"use strict";
+// Standard cryptographic implementations avoiding runtime ambient type dependencies
+// using node's built-in crypto module dynamically or via require for universal CommonJS compatibility
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryActionStore = void 0;
+exports.getOrGenerateLocalActionPolicySecret = getOrGenerateLocalActionPolicySecret;
+exports.canonicalizeJson = canonicalizeJson;
+exports.computeParametersHash = computeParametersHash;
+exports.signCapabilityPayload = signCapabilityPayload;
+exports.verifyCapabilitySignature = verifyCapabilitySignature;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const crypto = require('crypto');
+let cachedEphemeralSecret = null;
+/**
+ * Resolves the action policy secret key.
+ * In production (NODE_ENV=production), ACTION_POLICY_SECRET is required.
+ * In local/development environments, if no secret is provided via environment
+ * or options, generates an ephemeral cryptographically strong secret per-process,
+ * avoiding shared hardcoded fallback secrets.
+ */
+function getOrGenerateLocalActionPolicySecret(provided) {
+    if (provided) {
+        return provided;
+    }
+    const envSecret = typeof process !== 'undefined' && process.env ? process.env.ACTION_POLICY_SECRET : undefined;
+    if (envSecret) {
+        return envSecret;
+    }
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') {
+        throw new Error('FATAL: ACTION_POLICY_SECRET is required in production environment');
+    }
+    if (!cachedEphemeralSecret) {
+        cachedEphemeralSecret = crypto.randomBytes(32).toString('hex');
+    }
+    return cachedEphemeralSecret;
+}
+class InMemoryActionStore {
+    executions = new Map();
+    approvals = new Map();
+    auditLog = [];
+    lastAuditHash = '0000000000000000000000000000000000000000000000000000000000000000';
+    async reserveExecution(record) {
+        if (this.executions.has(record.executionId)) {
+            return false;
+        }
+        this.executions.set(record.executionId, { ...record });
+        return true;
+    }
+    async updateExecution(record) {
+        this.executions.set(record.executionId, { ...record });
+    }
+    async getExecution(executionId) {
+        const rec = this.executions.get(executionId);
+        return rec ? { ...rec } : undefined;
+    }
+    async saveApproval(executionId, approverActorId, reason) {
+        this.approvals.set(executionId, {
+            approverActorId,
+            reason,
+            approvedAt: new Date().toISOString(),
+        });
+    }
+    async isActionApproved(executionId) {
+        return this.approvals.has(executionId);
+    }
+    async appendAudit(event) {
+        const prevHash = this.lastAuditHash;
+        // Tamper-evident hash chaining over all security-critical event fields
+        const eventPayload = {
+            executionId: event.executionId,
+            actionId: event.actionId,
+            toolName: event.toolName,
+            providerId: event.providerId || null,
+            companionId: event.companionId,
+            actorId: event.actorId || null,
+            sessionId: event.sessionId || null,
+            channel: event.channel || null,
+            correlationId: event.correlationId || null,
+            riskLevel: event.riskLevel,
+            lifecycle: event.lifecycle,
+            decision: event.decision ? {
+                allowed: event.decision.allowed,
+                reason: event.decision.reason,
+                riskLevel: event.decision.riskLevel,
+                decisionCode: event.decision.decisionCode,
+            } : null,
+            parametersHash: event.parametersHash || null,
+            error: event.error || null,
+            timestamp: event.timestamp,
+        };
+        const canonical = canonicalizeJson(eventPayload);
+        const eventHash = crypto
+            .createHash('sha256')
+            .update(`${prevHash}:${canonical}`, 'utf8')
+            .digest('hex');
+        this.lastAuditHash = eventHash;
+        const recordWithHash = {
+            ...event,
+            previousEventHash: prevHash,
+            eventHash,
+            resultHash: event.resultHash || eventHash,
+        };
+        this.auditLog.push(recordWithHash);
+    }
+    async getAuditLog(executionId) {
+        if (executionId) {
+            return this.auditLog.filter((e) => e.executionId === executionId).map((e) => ({ ...e }));
+        }
+        return this.auditLog.map((e) => ({ ...e }));
+    }
+}
+exports.InMemoryActionStore = InMemoryActionStore;
+function canonicalizeJson(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return JSON.stringify(obj);
+    }
+    if (Array.isArray(obj)) {
+        return `[${obj.map(canonicalizeJson).join(',')}]`;
+    }
+    const keys = Object.keys(obj).sort();
+    const pairs = keys.map((k) => `"${k}":${canonicalizeJson(obj[k])}`);
+    return `{${pairs.join(',')}}`;
+}
+function computeParametersHash(params) {
+    const canonical = canonicalizeJson(params || {});
+    return crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+function signCapabilityPayload(payload, secretKey) {
+    const resolvedKey = getOrGenerateLocalActionPolicySecret(secretKey);
+    const canonicalStr = canonicalizeJson(payload);
+    return crypto.createHmac('sha256', resolvedKey).update(canonicalStr, 'utf8').digest('hex');
+}
+function verifyCapabilitySignature(capability, secretKey) {
+    if (!capability || capability.allowed !== true || typeof capability.signature !== 'string') {
+        return false;
+    }
+    const resolvedKey = getOrGenerateLocalActionPolicySecret(secretKey);
+    const { signature, allowed, ...rest } = capability;
+    const canonicalStr = canonicalizeJson(rest);
+    const expectedSigHex = crypto.createHmac('sha256', resolvedKey).update(canonicalStr, 'utf8').digest('hex');
+    // Constant-time comparison to prevent timing attacks
+    try {
+        const sigBuffer = globalThis.Buffer
+            ? globalThis.Buffer.from(signature, 'hex')
+            : new Uint8Array(signature.match(/.{1,2}/g)?.map((byte) => parseInt(byte, 16)) || []);
+        const expectedBuffer = globalThis.Buffer
+            ? globalThis.Buffer.from(expectedSigHex, 'hex')
+            : new Uint8Array(expectedSigHex.match(/.{1,2}/g)?.map((byte) => parseInt(byte, 16)) || []);
+        if (sigBuffer.length !== expectedBuffer.length || sigBuffer.length === 0) {
+            return false;
+        }
+        return crypto.timingSafeEqual(sigBuffer, expectedBuffer);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/capability.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/capability.test.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const crypto = require('crypto');
+const capability_1 = require("./capability");
+const action_policy_1 = require("./action-policy");
+describe('AuthorizationCapability Cryptographic & Tamper Review', () => {
+    const secretKey = 'prod_secret_signing_key';
+    let engine;
+    let sampleContext;
+    beforeEach(() => {
+        engine = new action_policy_1.ActionPolicyEngine({
+            secretKey,
+            defaultRiskLevel: 'LOW',
+        });
+        sampleContext = {
+            companionId: 'comp-alpha',
+            actor: {
+                actorId: 'user-77',
+                sessionId: 'sess-88',
+                authorizationRole: 'operator',
+                capabilities: ['tool:send_email'],
+                authenticated: true,
+            },
+            conversation: {
+                channel: 'direct',
+                audienceId: 'aud-alpha',
+                correlationId: 'corr-999',
+            },
+        };
+        engine.registerToolDefinition({
+            name: 'send_email',
+            providerId: 'comm',
+            description: 'Send email',
+            inputSchema: {},
+            riskLevel: 'LOW',
+            requiredCapabilities: ['tool:send_email'],
+        });
+    });
+    describe('Field-Level Tampering Invalidation (HMAC-SHA-256)', () => {
+        let legitCapability;
+        beforeEach(async () => {
+            const { capability } = await engine.evaluateAction({
+                actionId: 'act-email-1',
+                toolName: 'comm/send_email',
+                parameters: { to: 'alice@example.com', subject: 'Hello' },
+                context: sampleContext,
+            });
+            expect(capability).toBeDefined();
+            legitCapability = capability;
+        });
+        it('verifies untouched authentic capability', () => {
+            expect((0, capability_1.verifyCapabilitySignature)(legitCapability, secretKey)).toBe(true);
+        });
+        it('invalidates signature if executionId is modified', () => {
+            const tampered = { ...legitCapability, executionId: 'exec-tampered-999' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if actionId is modified', () => {
+            const tampered = { ...legitCapability, actionId: 'act-tampered-999' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if toolName is modified', () => {
+            const tampered = { ...legitCapability, toolName: 'admin/delete_all' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if providerId is modified', () => {
+            const tampered = { ...legitCapability, providerId: 'untrusted_plugin' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if parametersHash is modified', () => {
+            const tampered = { ...legitCapability, parametersHash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if actorId is modified', () => {
+            const tampered = { ...legitCapability, actorId: 'attacker-root' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if sessionId is modified', () => {
+            const tampered = { ...legitCapability, sessionId: 'hijacked-session' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if channel is modified', () => {
+            const tampered = { ...legitCapability, channel: 'public' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if correlationId is modified', () => {
+            const tampered = { ...legitCapability, correlationId: 'corr-spoofed' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if expiresAt is modified to extend lifetime', () => {
+            const tampered = { ...legitCapability, expiresAt: new Date(Date.now() + 86400000).toISOString() };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if issuedAt is modified', () => {
+            const tampered = { ...legitCapability, issuedAt: new Date(Date.now() - 100000).toISOString() };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('rejects verification if secretKey is mismatched', () => {
+            expect((0, capability_1.verifyCapabilitySignature)(legitCapability, 'wrong_secret_key')).toBe(false);
+        });
+        it('handles malformed, truncated, or non-hex signatures safely without crashing', () => {
+            const malformed1 = { ...legitCapability, signature: 'not_a_hex_string' };
+            expect((0, capability_1.verifyCapabilitySignature)(malformed1, secretKey)).toBe(false);
+            const malformed2 = { ...legitCapability, signature: 'deadbeef' };
+            expect((0, capability_1.verifyCapabilitySignature)(malformed2, secretKey)).toBe(false);
+            const malformed3 = { ...legitCapability, signature: '' };
+            expect((0, capability_1.verifyCapabilitySignature)(malformed3, secretKey)).toBe(false);
+        });
+    });
+    describe('Deterministic Canonicalization', () => {
+        it('produces identical canonical JSON strings regardless of key insertion order', () => {
+            const objA = { b: 2, a: 1, c: { z: 26, y: 25 } };
+            const objB = { a: 1, c: { y: 25, z: 26 }, b: 2 };
+            expect((0, capability_1.canonicalizeJson)(objA)).toBe((0, capability_1.canonicalizeJson)(objB));
+            expect((0, capability_1.computeParametersHash)(objA)).toBe((0, capability_1.computeParametersHash)(objB));
+        });
+    });
+    describe('Audit Trail SHA-256 Hash Chaining and Mutation Detection', () => {
+        it('detects tampering or mutation in previous audit events in the chain', async () => {
+            const store = new capability_1.InMemoryActionStore();
+            const policyEngine = new action_policy_1.ActionPolicyEngine({ store, secretKey });
+            policyEngine.registerToolDefinition({
+                name: 'send_email',
+                providerId: 'comm',
+                description: 'Send email',
+                inputSchema: {},
+                riskLevel: 'LOW',
+            });
+            // Event 1
+            await policyEngine.evaluateAction({
+                actionId: 'act-1',
+                toolName: 'comm/send_email',
+                parameters: { step: 1 },
+                context: sampleContext,
+            });
+            // Event 2
+            await policyEngine.evaluateAction({
+                actionId: 'act-2',
+                toolName: 'comm/send_email',
+                parameters: { step: 2 },
+                context: sampleContext,
+            });
+            const auditTrail = await store.getAuditLog();
+            expect(auditTrail.length).toBe(2);
+            const event1 = auditTrail[0];
+            const event2 = auditTrail[1];
+            // Recompute expected hash chain using standard SHA-256
+            const initialPrevHash = '0000000000000000000000000000000000000000000000000000000000000000';
+            const canonical1 = (0, capability_1.canonicalizeJson)({
+                executionId: event1.executionId,
+                actionId: event1.actionId,
+                toolName: event1.toolName,
+                providerId: event1.providerId || null,
+                companionId: event1.companionId,
+                actorId: event1.actorId || null,
+                sessionId: event1.sessionId || null,
+                channel: event1.channel || null,
+                correlationId: event1.correlationId || null,
+                riskLevel: event1.riskLevel,
+                lifecycle: event1.lifecycle,
+                decision: event1.decision ? {
+                    allowed: event1.decision.allowed,
+                    reason: event1.decision.reason,
+                    riskLevel: event1.decision.riskLevel,
+                    decisionCode: event1.decision.decisionCode,
+                } : null,
+                parametersHash: event1.parametersHash || null,
+                error: event1.error || null,
+                timestamp: event1.timestamp,
+            });
+            const expectedHash1 = crypto.createHash('sha256').update(`${initialPrevHash}:${canonical1}`, 'utf8').digest('hex');
+            expect(event1.eventHash).toBe(expectedHash1);
+            expect(event1.previousEventHash).toBe(initialPrevHash);
+            const canonical2 = (0, capability_1.canonicalizeJson)({
+                executionId: event2.executionId,
+                actionId: event2.actionId,
+                toolName: event2.toolName,
+                providerId: event2.providerId || null,
+                companionId: event2.companionId,
+                actorId: event2.actorId || null,
+                sessionId: event2.sessionId || null,
+                channel: event2.channel || null,
+                correlationId: event2.correlationId || null,
+                riskLevel: event2.riskLevel,
+                lifecycle: event2.lifecycle,
+                decision: event2.decision ? {
+                    allowed: event2.decision.allowed,
+                    reason: event2.decision.reason,
+                    riskLevel: event2.decision.riskLevel,
+                    decisionCode: event2.decision.decisionCode,
+                } : null,
+                parametersHash: event2.parametersHash || null,
+                error: event2.error || null,
+                timestamp: event2.timestamp,
+            });
+            const expectedHash2 = crypto.createHash('sha256').update(`${expectedHash1}:${canonical2}`, 'utf8').digest('hex');
+            expect(event2.eventHash).toBe(expectedHash2);
+            expect(event2.previousEventHash).toBe(expectedHash1);
+            // If an attacker altered event 1 retrospectively, the hash chain breaks for event 2
+            const tamperedCanonical1 = (0, capability_1.canonicalizeJson)({
+                ...JSON.parse(canonical1),
+                actionId: 'act-tampered-1',
+            });
+            const tamperedHash1 = crypto.createHash('sha256').update(`${initialPrevHash}:${tamperedCanonical1}`, 'utf8').digest('hex');
+            const brokenHash2 = crypto.createHash('sha256').update(`${tamperedHash1}:${canonical2}`, 'utf8').digest('hex');
+            expect(brokenHash2).not.toBe(event2.resultHash);
+        });
+    });
+    describe('Durable Action Approval Restart Semantics', () => {
+        it('preserves approved execution authorization across ActionPolicyEngine process restart', async () => {
+            const sharedStore = new capability_1.InMemoryActionStore();
+            // Instance 1: Operator reviews and approves a HIGH risk action
+            const engine1 = new action_policy_1.ActionPolicyEngine({
+                store: sharedStore,
+                secretKey,
+                defaultRiskLevel: 'HIGH',
+                defaultRequireApprovalForHighRisk: true,
+            });
+            engine1.registerToolDefinition({
+                name: 'database/cleanup',
+                providerId: 'db',
+                description: 'Cleanup DB',
+                inputSchema: {},
+                riskLevel: 'HIGH',
+                requiresApproval: true,
+            });
+            const highRiskAction = {
+                actionId: 'act-restart-1',
+                executionId: 'exec-restart-1',
+                toolName: 'db/database/cleanup',
+                parameters: { target: 'logs' },
+                context: sampleContext,
+            };
+            // 1. Initial evaluation without approval is rejected
+            const eval1 = await engine1.evaluateAction(highRiskAction);
+            expect(eval1.decision.allowed).toBe(false);
+            expect(eval1.decision.decisionCode).toBe('REJECTED_HIGH_RISK_UNAPPROVED');
+            // 2. Operator explicitly approves
+            await engine1.approveAction({
+                executionId: 'exec-restart-1',
+                approverActorId: 'operator-1',
+                reason: 'Scheduled maintenance',
+            });
+            // 3. Process restarts: new ActionPolicyEngine instance with empty in-memory set but shared durable store
+            const engine2 = new action_policy_1.ActionPolicyEngine({
+                store: sharedStore,
+                secretKey,
+                defaultRiskLevel: 'HIGH',
+                defaultRequireApprovalForHighRisk: true,
+            });
+            engine2.registerToolDefinition({
+                name: 'database/cleanup',
+                providerId: 'db',
+                description: 'Cleanup DB',
+                inputSchema: {},
+                riskLevel: 'HIGH',
+                requiresApproval: true,
+            });
+            // 4. Evaluation after restart loads durable approval and successfully authorizes capability
+            const eval2 = await engine2.evaluateAction(highRiskAction);
+            expect(eval2.decision.allowed).toBe(true);
+            expect(eval2.decision.decisionCode).toBe('ALLOWED_POLICY');
+            expect(eval2.capability).toBeDefined();
+            expect(eval2.capability?.executionId).toBe('exec-restart-1');
+            expect((0, capability_1.verifyCapabilitySignature)(eval2.capability, secretKey)).toBe(true);
+        });
+    });
+});

package/dist/chat-contract.d.ts

@@ -0,0 +1,81 @@
+import { RequestContext } from './context';
+import { Message, Claim } from './index';
+import { ActionExecutionResult } from './action';
+import { ResponseCitation } from './evidence';
+import { SiduriRuntime } from './runtime';
+import { MouthMedium, FormattedMouthOutput } from './mouth-types';
+export interface ChatRequest {
+    id?: string;
+    companionId?: string;
+    message: string;
+    role?: 'OWNER' | 'VIEWER' | 'OPERATOR' | string;
+    context?: RequestContext;
+    history?: Message[];
+    medium?: MouthMedium;
+    signal?: AbortSignal;
+    [key: string]: any;
+}
+export interface ChatResponseMetadataEvent {
+    event_id: string;
+    kind: string;
+    lifecycle: string;
+    approval?: string;
+    expression?: string;
+    action?: string;
+    durationMs?: number;
+}
+export interface ChatResponsePlan {
+    speech_id?: string;
+    audio_url?: string;
+    subtitle_ja: string;
+    subtitle_en: string;
+    spoken_ja?: string;
+    evidence_ids?: string[];
+}
+export interface ChatResponseMetadata {
+    language?: string;
+    proposals?: Claim[];
+    memory_proposals?: Array<{
+        proposal_id: string;
+        subject?: string;
+        predicate?: string;
+        value?: string;
+        status: string;
+        content?: string;
+        claim_type?: string;
+    }>;
+    behavioral_proposals?: Array<{
+        directive_id: string;
+        memory_class: string;
+        domain: string;
+        subject: string;
+        predicate: string;
+        value: string;
+        status: string;
+        behavior?: any;
+        runtime_effect?: string;
+    }>;
+    action_results?: ActionExecutionResult[];
+    evidence_ids?: string[];
+    citations?: ResponseCitation[];
+    subsystem_diagnostics?: Record<string, string>;
+    events?: ChatResponseMetadataEvent[];
+    [key: string]: any;
+}
+export interface ChatResponse {
+    status: 'APPROVED' | 'REJECTED' | 'STAGED' | string;
+    response_id?: string;
+    correlation_id?: string;
+    response: ChatResponsePlan;
+    metadata?: ChatResponseMetadata;
+    delivery?: FormattedMouthOutput;
+    reply?: string;
+    text?: string;
+    audioUrl?: string;
+    expression?: string;
+}
+/**
+ * Canonical helper to dispatch a chat request to a SiduriRuntime instance.
+ * Guarantees a 1:1 identical response structure for localweb (apps/api) and standalone CLI.
+ */
+export declare function dispatchCompanionChat(runtime: SiduriRuntime, payload: ChatRequest): Promise<ChatResponse>;

package/dist/chat-contract.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchCompanionChat = dispatchCompanionChat;
+/**
+ * Canonical helper to dispatch a chat request to a SiduriRuntime instance.
+ * Guarantees a 1:1 identical response structure for localweb (apps/api) and standalone CLI.
+ */
+async function dispatchCompanionChat(runtime, payload) {
+    const userMessage = payload.message || payload.text || '';
+    const history = Array.isArray(payload.history) ? payload.history : [];
+    let roleOrContext;
+    if (payload.context) {
+        roleOrContext = payload.context;
+    }
+    else if (payload.role) {
+        roleOrContext = payload.role;
+    }
+    else {
+        roleOrContext = 'OWNER';
+    }
+    const runtimeResult = (payload.medium || payload.signal)
+        ? await runtime.handleUserMessage(userMessage, roleOrContext, history, payload.medium, payload.signal)
+        : await runtime.handleUserMessage(userMessage, roleOrContext, history);
+    const delivery = runtimeResult?.delivery;
+    // Normalize response plan
+    const speech = delivery?.displayText ||
+        delivery?.text ||
+        runtimeResult?.response?.subtitle_ja ||
+        runtimeResult?.response?.subtitle_en ||
+        '';
+    const audioUrl = delivery?.audioUrl || runtimeResult?.response?.audio_url;
+    // Extract avatar expression if any event was generated or provided by Mouth delivery
+    let expression = delivery?.expression || 'neutral';
+    if (expression === 'neutral') {
+        const events = runtimeResult?.metadata?.events || [];
+        const avatarEvent = events.find((e) => e.kind === 'avatar' || e.kind === 'body');
+        if (avatarEvent && avatarEvent.expression) {
+            expression = avatarEvent.expression;
+        }
+    }
+    // Ensure both spoken_ja and subtitle_en are accessible alongside speech_id and evidence_ids
+    const responsePlan = {
+        speech_id: runtimeResult?.response?.speech_id,
+        audio_url: audioUrl,
+        subtitle_ja: delivery?.subtitles?.ja ?? runtimeResult?.response?.subtitle_ja ?? speech,
+        subtitle_en: delivery?.subtitles?.en ?? runtimeResult?.response?.subtitle_en ?? speech,
+        spoken_ja: delivery?.subtitles?.spoken ?? runtimeResult?.response?.spoken_ja ?? runtimeResult?.response?.subtitle_ja ?? speech,
+        evidence_ids: runtimeResult?.metadata?.evidence_ids ?? runtimeResult?.response?.evidence_ids ?? [],
+    };
+    const metadata = {
+        ...(runtimeResult?.metadata || {}),
+    };
+    delete metadata.internal_monologue;
+    delete metadata.internalMonologue;
+    return {
+        status: runtimeResult?.status || 'APPROVED',
+        response_id: runtimeResult?.response_id,
+        correlation_id: runtimeResult?.correlation_id,
+        response: responsePlan,
+        delivery,
+        metadata,
+        // Convenience fields for legacy/simple consumers
+        reply: speech,
+        text: speech,
+        audioUrl,
+        expression,
+    };
+}

package/dist/cognition-planner.d.ts

@@ -0,0 +1,15 @@
+import { BrainOrgan, Message, ResponsePlan, MemoryScope } from './index';
+export interface CognitionPlanningParams {
+    companionName: string;
+    brain?: BrainOrgan;
+    systemPrompt: string;
+    contextPrompt: string;
+    recentMessages: Message[];
+    recipient?: MemoryScope;
+    perceivedText: string;
+}
+/**
+ * Invokes BrainOrgan to generate a structured ResponsePlan, or provides
+ * a graceful baseline response if Brain is absent or in headless passive mode.
+ */
+export declare function generateCognitionPlan(params: CognitionPlanningParams): Promise<ResponsePlan>;