@siduri-x/core 2.0.1 → 2.0.3

package/dist/action-policy.d.ts

@@ -18,7 +18,7 @@ export interface ActionPolicyEngineOptions {
     allowedApproverRoles?: string[];
     requiredApproverCapabilities?: string[];
 }
-export type ActionApprovalDecisionCode = 'APPROVED' | 'REJECTED_UNAUTHORIZED' | 'REJECTED_UNAUTHENTICATED' | 'REJECTED_ROLE_MISMATCH' | 'REJECTED_MISSING_APPROVER_ID' | 'REJECTED_MISSING_CAPABILITY';
+export type ActionApprovalDecisionCode = 'APPROVED' | 'REJECTED_UNAUTHORIZED' | 'REJECTED_UNAUTHENTICATED' | 'REJECTED_ROLE_MISMATCH' | 'REJECTED_MISSING_APPROVER_ID' | 'REJECTED_MISSING_CAPABILITY' | 'REJECTED_UNKNOWN_EXECUTION';
 export interface ActionApprovalResult {
     approved: boolean;
     decisionCode: ActionApprovalDecisionCode;
@@ -42,6 +42,13 @@ export interface ApproveActionOptions {
      * Optional capabilities held by the approver.
      */
     approverCapabilities?: string[];
+    /**
+     * Optional explicit action binding parameters when pre-authorizing a known action
+     */
+    toolName?: string;
+    parametersHash?: string;
+    companionId?: string;
+    actorId?: string;
 }
 export declare function normalizeApproverRole(role?: string, actorId?: string): string;
 export declare class ActionPolicyEngine {

package/dist/action-policy.js

@@ -10,18 +10,10 @@ function normalizeApproverRole(role, actorId) {
             return 'administrator';
         return lower;
     }
-    if (actorId) {
-        const lower = actorId.toLowerCase();
-        if (lower.includes('admin'))
-            return 'administrator';
-        if (lower.includes('owner'))
-            return 'owner';
-        if (lower.includes('operator'))
-            return 'operator';
-        if (lower.includes('viewer') || lower.includes('guest') || lower.includes('visitor'))
-            return 'viewer';
-    }
-    return 'owner'; // Default to single-owner role
+    // Principle of least privilege: Never derive privileged roles (administrator, owner, operator)
+    // from arbitrary substring matching on unverified actorId strings.
+    // When an explicit authorization role is not provided, default to 'viewer'.
+    return 'viewer';
 }
 class ActionPolicyEngine {
     toolRegistry = new Map();
@@ -96,7 +88,9 @@ class ActionPolicyEngine {
         }
         // Role check if tool restricts roles (supports administrator/owner role parity)
         if (toolDef.allowedRoles && toolDef.allowedRoles.length > 0) {
-            const actorRole = effectiveContext.actor.authorizationRole || effectiveContext.actor.role || 'owner';
+            const actorRole = effectiveContext.actor.authorizationRole ||
+                effectiveContext.actor.role ||
+                (effectiveContext.actor.authenticated === false ? 'viewer' : 'owner');
             const normalizedActorRoles = new Set([actorRole.toLowerCase()]);
             if (actorRole.toLowerCase() === 'administrator' || actorRole.toLowerCase() === 'owner') {
                 normalizedActorRoles.add('administrator');
@@ -158,6 +152,26 @@ class ActionPolicyEngine {
                 this.approvedExecutions.set(executionId, approvalRecord);
             }
         }
+        // Cryptographic / structural binding verification:
+        // Ensure the approval record matches the exact tool, parameters, companion, and actor
+        if (approvalRecord) {
+            const toolMatch = !approvalRecord.toolName || approvalRecord.toolName === action.toolName;
+            const paramsMatch = !approvalRecord.parametersHash || approvalRecord.parametersHash === paramsHash;
+            const companionMatch = !approvalRecord.companionId || approvalRecord.companionId === effectiveContext.companionId;
+            const actorMatch = !approvalRecord.actorId || approvalRecord.actorId === effectiveContext.actor.actorId;
+            if (!toolMatch || !paramsMatch || !companionMatch || !actorMatch) {
+                const decision = {
+                    allowed: false,
+                    reason: `Approval record for execution "${executionId}" does not match the requested tool, parameters, companion, or actor`,
+                    riskLevel,
+                    requiredCapabilities: requiredCaps,
+                    executionId,
+                    decisionCode: 'REJECTED_APPROVAL_MISMATCH',
+                };
+                await this.recordAudit(action, effectiveContext, decision, 'REJECTED');
+                return { decision };
+            }
+        }
         let isApproved = Boolean(approvalRecord);
         if (!isApproved && typeof this.store.isActionApproved === 'function') {
             isApproved = await this.store.isActionApproved(executionId);
@@ -183,6 +197,27 @@ class ActionPolicyEngine {
         }
         if (requiresExplicitApproval && !isApproved) {
             this.pendingActions.set(executionId, { action, context: effectiveContext, toolDef });
+            if (typeof this.store.reserveExecution === 'function') {
+                const record = {
+                    executionId,
+                    actionId: action.actionId,
+                    toolName: action.toolName,
+                    providerId: toolDef.providerId || 'builtin',
+                    parametersHash: paramsHash,
+                    lifecycle: 'POLICY_CHECKED',
+                    decision: {
+                        allowed: false,
+                        reason: `Action "${action.toolName}" has risk level ${riskLevel} and requires explicit approval`,
+                        riskLevel,
+                        requiredCapabilities: requiredCaps,
+                        executionId,
+                        decisionCode: 'REJECTED_HIGH_RISK_UNAPPROVED',
+                    },
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                };
+                await this.store.reserveExecution(record).catch(() => { });
+            }
             const decision = {
                 allowed: false,
                 reason: `Action "${action.toolName}" has risk level ${riskLevel} and requires explicit approval`,
@@ -271,21 +306,42 @@ class ActionPolicyEngine {
             await this.recordApprovalAudit(options.executionId, actorId, approverRole, false, result.reason);
             return result;
         }
-        // 3. Tool-specific authorization check if pending action is registered
+        // 3. Locate pending in-memory action or persisted execution record
         const pending = this.pendingActions.get(options.executionId);
-        if (pending) {
-            const { toolDef } = pending;
-            if (toolDef.allowedRoles && toolDef.allowedRoles.length > 0 && !isOwnerOrAdmin) {
-                const normalizedToolRoles = new Set(toolDef.allowedRoles.map((r) => r.toLowerCase()));
+        let executionRecord;
+        if (!pending && typeof this.store.getExecution === 'function') {
+            executionRecord = await this.store.getExecution(options.executionId);
+        }
+        if (!pending && !executionRecord && !options.toolName) {
+            const result = {
+                approved: false,
+                decisionCode: 'REJECTED_UNKNOWN_EXECUTION',
+                reason: `Cannot approve execution "${options.executionId}": execution is not pending or recognized`,
+                executionId: options.executionId,
+                approverActorId: actorId,
+            };
+            await this.recordApprovalAudit(options.executionId, actorId, approverRole, false, result.reason);
+            return result;
+        }
+        const targetToolName = pending?.action.toolName || executionRecord?.toolName || options.toolName || '';
+        const targetToolDef = pending?.toolDef || (targetToolName ? this.findToolDefinition(targetToolName) : undefined);
+        const targetParamsHash = (pending ? (0, capability_1.computeParametersHash)(pending.action.parameters) : undefined) ||
+            executionRecord?.parametersHash ||
+            options.parametersHash;
+        const targetCompanionId = pending?.context?.companionId || pending?.action.context?.companionId || options.companionId;
+        const targetActorId = pending?.context?.actor.actorId || pending?.action.context?.actor.actorId || options.actorId;
+        if (targetToolDef) {
+            if (targetToolDef.allowedRoles && targetToolDef.allowedRoles.length > 0 && !isOwnerOrAdmin) {
+                const normalizedToolRoles = new Set(targetToolDef.allowedRoles.map((r) => r.toLowerCase()));
                 if (!normalizedToolRoles.has(approverRole)) {
                     const result = {
                         approved: false,
                         decisionCode: 'REJECTED_ROLE_MISMATCH',
-                        reason: `Approver role "${approverRole}" is not authorized to approve tool "${toolDef.name}" (requires: ${toolDef.allowedRoles.join(', ')})`,
+                        reason: `Approver role "${approverRole}" is not authorized to approve tool "${targetToolDef.name}" (requires: ${targetToolDef.allowedRoles.join(', ')})`,
                         executionId: options.executionId,
                         approverActorId: actorId,
                     };
-                    await this.recordApprovalAudit(options.executionId, actorId, approverRole, false, result.reason, toolDef.name);
+                    await this.recordApprovalAudit(options.executionId, actorId, approverRole, false, result.reason, targetToolDef.name);
                     return result;
                 }
             }
@@ -299,25 +355,29 @@ class ActionPolicyEngine {
                         executionId: options.executionId,
                         approverActorId: actorId,
                     };
-                    await this.recordApprovalAudit(options.executionId, actorId, approverRole, false, result.reason, toolDef.name);
+                    await this.recordApprovalAudit(options.executionId, actorId, approverRole, false, result.reason, targetToolDef.name);
                     return result;
                 }
             }
         }
-        // 4. Record verified approval
+        // 4. Record verified approval with exact tool, parameter, companion, and actor binding
         const record = {
             executionId: options.executionId,
             approverActorId: actorId,
             reason: options.reason,
             approverRole,
             approvedAt: new Date().toISOString(),
+            toolName: targetToolName,
+            parametersHash: targetParamsHash,
+            companionId: targetCompanionId,
+            actorId: targetActorId,
         };
         this.approvedExecutions.set(options.executionId, record);
         if (typeof this.store.saveApproval === 'function') {
-            await this.store.saveApproval(options.executionId, actorId, options.reason, approverRole);
+            await this.store.saveApproval(options.executionId, actorId, options.reason, approverRole, targetToolName, targetParamsHash, targetCompanionId, targetActorId);
         }
         const reason = options.reason || 'Action approved by authorized policy approver';
-        await this.recordApprovalAudit(options.executionId, actorId, approverRole, true, reason, pending?.toolDef.name);
+        await this.recordApprovalAudit(options.executionId, actorId, approverRole, true, reason, targetToolName);
         return {
             approved: true,
             decisionCode: 'APPROVED',

package/dist/action-policy.test.js

@@ -125,9 +125,10 @@ describe('ActionPolicyEngine Boundary', () => {
         expect(res1.decision.decisionCode).toBe('REJECTED_HIGH_RISK_UNAPPROVED');
         expect(res1.capability).toBeUndefined();
         // Grant explicit approval
-        engine.approveAction({
+        await engine.approveAction({
             executionId: 'exec-admin-delete-1',
             approverActorId: 'admin-super-user',
+            approverRole: 'administrator',
         });
         // Second attempt: approved
         const res2 = await engine.evaluateAction(action);
@@ -293,5 +294,70 @@ describe('ActionPolicyEngine Boundary', () => {
             expect(rejectionEvent?.actorId).toBe('viewer-tamper');
             expect(rejectionEvent?.decision?.decisionCode).toBe('REJECTED_UNAUTHORIZED');
         });
+        it('rejects approval attempt for arbitrary unknown execution ID', async () => {
+            const res = await engine.approveAction({
+                executionId: 'arbitrary-unregistered-id',
+                approverActorId: 'admin-bob',
+                approverRole: 'administrator',
+            });
+            expect(res.approved).toBe(false);
+            expect(res.decisionCode).toBe('REJECTED_UNKNOWN_EXECUTION');
+        });
+        it('rejects privilege escalation from actorId strings (attacker-admin is not an administrator without explicit role)', async () => {
+            await engine.evaluateAction(criticalAction);
+            const res = await engine.approveAction({
+                executionId: 'exec-sec-auth-1',
+                approverActorId: 'attacker-admin-user',
+                // Notice no approverRole is provided!
+            });
+            expect(res.approved).toBe(false);
+            expect(res.decisionCode).toBe('REJECTED_UNAUTHORIZED');
+        });
+        it('rejects action evaluation if parameters are tampered after approval (REJECTED_APPROVAL_MISMATCH)', async () => {
+            await engine.evaluateAction(criticalAction);
+            const approval = await engine.approveAction({
+                executionId: 'exec-sec-auth-1',
+                approverActorId: 'admin-bob',
+                approverRole: 'administrator',
+            });
+            expect(approval.approved).toBe(true);
+            // Attacker re-evaluates the same approved executionId but with injected dangerous parameters
+            const tamperedAction = {
+                ...criticalAction,
+                parameters: { injected: 'malicious-payload' },
+            };
+            const evalTampered = await engine.evaluateAction(tamperedAction);
+            expect(evalTampered.decision.allowed).toBe(false);
+            expect(evalTampered.decision.decisionCode).toBe('REJECTED_APPROVAL_MISMATCH');
+            expect(evalTampered.capability).toBeUndefined();
+        });
+        it('rejects action evaluation if tool name is swapped after approval (REJECTED_APPROVAL_MISMATCH)', async () => {
+            await engine.evaluateAction(criticalAction);
+            const approval = await engine.approveAction({
+                executionId: 'exec-sec-auth-1',
+                approverActorId: 'admin-bob',
+                approverRole: 'administrator',
+            });
+            expect(approval.approved).toBe(true);
+            // Register another tool
+            engine.registerToolDefinition({
+                name: 'admin/format_drive',
+                providerId: 'admin',
+                description: 'Format drive',
+                inputSchema: {},
+                riskLevel: 'CRITICAL',
+                allowedRoles: ['administrator'],
+                requiresApproval: true,
+            });
+            // Attacker re-uses the executionId on a different tool
+            const swappedAction = {
+                ...criticalAction,
+                toolName: 'admin/format_drive',
+            };
+            const evalSwapped = await engine.evaluateAction(swappedAction);
+            expect(evalSwapped.decision.allowed).toBe(false);
+            expect(evalSwapped.decision.decisionCode).toBe('REJECTED_APPROVAL_MISMATCH');
+            expect(evalSwapped.capability).toBeUndefined();
+        });
     });
 });

package/dist/action.d.ts

@@ -15,7 +15,7 @@ export interface ActionPolicyDecision {
     riskLevel: ActionRiskLevel;
     requiredCapabilities?: string[];
     executionId: string;
-    decisionCode: 'ALLOWED_AUTO' | 'ALLOWED_POLICY' | 'REJECTED_UNKNOWN_TOOL' | 'REJECTED_UNAUTHORIZED' | 'REJECTED_MISSING_CAPABILITY' | 'REJECTED_HIGH_RISK_UNAPPROVED' | 'REJECTED_CHANNEL_RESTRICTED' | 'REJECTED_COMPANION_MISMATCH' | 'REJECTED_POLICY';
+    decisionCode: 'ALLOWED_AUTO' | 'ALLOWED_POLICY' | 'REJECTED_UNKNOWN_TOOL' | 'REJECTED_UNAUTHORIZED' | 'REJECTED_MISSING_CAPABILITY' | 'REJECTED_HIGH_RISK_UNAPPROVED' | 'REJECTED_CHANNEL_RESTRICTED' | 'REJECTED_COMPANION_MISMATCH' | 'REJECTED_APPROVAL_MISMATCH' | 'REJECTED_POLICY';
 }
 export interface ActionAuditEvent {
     executionId: string;

package/dist/capability.d.ts

@@ -43,12 +43,16 @@ export interface ActionApprovalRecord {
     reason?: string;
     approvedAt: string;
     approverRole?: string;
+    toolName?: string;
+    parametersHash?: string;
+    companionId?: string;
+    actorId?: 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, approverRole?: string): Promise<void>;
+    saveApproval(executionId: string, approverActorId: string, reason?: string, approverRole?: string, toolName?: string, parametersHash?: string, companionId?: string, actorId?: string): Promise<void>;
     isActionApproved(executionId: string): Promise<boolean>;
     getApproval?(executionId: string): Promise<ActionApprovalRecord | undefined>;
     appendAudit(event: ActionAuditEvent): Promise<void>;
@@ -62,7 +66,7 @@ export declare class InMemoryActionStore implements ActionStore {
     reserveExecution(record: PersistentExecutionRecord): Promise<boolean>;
     updateExecution(record: PersistentExecutionRecord): Promise<void>;
     getExecution(executionId: string): Promise<PersistentExecutionRecord | undefined>;
-    saveApproval(executionId: string, approverActorId: string, reason?: string, approverRole?: string): Promise<void>;
+    saveApproval(executionId: string, approverActorId: string, reason?: string, approverRole?: string, toolName?: string, parametersHash?: string, companionId?: string, actorId?: string): Promise<void>;
     isActionApproved(executionId: string): Promise<boolean>;
     getApproval(executionId: string): Promise<ActionApprovalRecord | undefined>;
     appendAudit(event: ActionAuditEvent): Promise<void>;

package/dist/capability.js

@@ -53,13 +53,17 @@ class InMemoryActionStore {
         const rec = this.executions.get(executionId);
         return rec ? { ...rec } : undefined;
     }
-    async saveApproval(executionId, approverActorId, reason, approverRole) {
+    async saveApproval(executionId, approverActorId, reason, approverRole, toolName, parametersHash, companionId, actorId) {
         this.approvals.set(executionId, {
             executionId,
             approverActorId,
             reason,
             approverRole,
             approvedAt: new Date().toISOString(),
+            toolName,
+            parametersHash,
+            companionId,
+            actorId,
         });
     }
     async isActionApproved(executionId) {

package/dist/capability.test.js

@@ -281,6 +281,7 @@ describe('AuthorizationCapability Cryptographic & Tamper Review', () => {
             await engine1.approveAction({
                 executionId: 'exec-restart-1',
                 approverActorId: 'operator-1',
+                approverRole: 'operator',
                 reason: 'Scheduled maintenance',
             });
             // 3. Process restarts: new ActionPolicyEngine instance with empty in-memory set but shared durable store

package/dist/chat-contract.d.ts

@@ -78,4 +78,6 @@ export interface ChatResponse {
  * 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>;
+export declare function dispatchCompanionChat(runtime: SiduriRuntime | {
+    runtime: SiduriRuntime;
+}, payload: ChatRequest): Promise<ChatResponse>;

package/dist/chat-contract.js

@@ -6,6 +6,9 @@ exports.dispatchCompanionChat = dispatchCompanionChat;
  * Guarantees a 1:1 identical response structure for localweb (apps/api) and standalone CLI.
  */
 async function dispatchCompanionChat(runtime, payload) {
+    const runner = 'runtime' in runtime && typeof runtime.handleUserMessage !== 'function'
+        ? runtime.runtime
+        : runtime;
     const userMessage = payload.message || payload.text || '';
     const history = Array.isArray(payload.history) ? payload.history : [];
     let roleOrContext;
@@ -19,8 +22,8 @@ async function dispatchCompanionChat(runtime, payload) {
         roleOrContext = 'OWNER';
     }
     const runtimeResult = (payload.medium || payload.signal)
-        ? await runtime.handleUserMessage(userMessage, roleOrContext, history, payload.medium, payload.signal)
-        : await runtime.handleUserMessage(userMessage, roleOrContext, history);
+        ? await runner.handleUserMessage(userMessage, roleOrContext, history, payload.medium, payload.signal)
+        : await runner.handleUserMessage(userMessage, roleOrContext, history);
     const delivery = runtimeResult?.delivery;
     // Normalize response plan
     const speech = delivery?.displayText ||

package/dist/container.d.ts

@@ -0,0 +1,74 @@
+import { BrainOrgan, MemoryOrgan, VoiceOrgan, KnowledgeOrgan, VisionOrgan, BehaviorOrgan, BodyOrgan, HandsOrgan, EarOrgan, ObservationOrgan, MouthOrgan, SelfRepository, EKnowledgeOrgan, OrganConfig, ActionStore, ActionPolicyEngine, ResponseGatingEngine, ExperienceDispatcher, ExperienceAdapter } from './index';
+import { SessionHistoryManager } from './session-history';
+import { SiduriRuntime } from './runtime';
+export interface SiduriRuntimeConfig {
+    name: string;
+    brain?: OrganConfig | Record<string, unknown>;
+    voice?: OrganConfig | Record<string, unknown>;
+    memory?: OrganConfig | Record<string, unknown>;
+    knowledge?: OrganConfig | Record<string, unknown>;
+    behavior?: OrganConfig | Record<string, unknown>;
+    body?: OrganConfig | Record<string, unknown>;
+    vision?: OrganConfig | Record<string, unknown>;
+    hands?: OrganConfig | Record<string, unknown>;
+    ear?: OrganConfig | Record<string, unknown>;
+    observation?: OrganConfig | Record<string, unknown>;
+    mouth?: OrganConfig | Record<string, unknown>;
+    self?: OrganConfig | Record<string, unknown>;
+    externalKnowledge?: OrganConfig | Record<string, unknown>;
+    actionPolicy?: Record<string, unknown>;
+    actionStore?: 'in-memory' | 'sqlite' | {
+        type: 'sqlite' | 'in-memory';
+        dbPath?: string;
+    };
+    actionStorePath?: string;
+    [key: string]: unknown;
+}
+export interface RuntimeOrgans {
+    brain?: BrainOrgan;
+    memory?: MemoryOrgan;
+    voice?: VoiceOrgan | ExperienceAdapter;
+    knowledge?: KnowledgeOrgan;
+    vision?: VisionOrgan;
+    behavior?: BehaviorOrgan;
+    body?: BodyOrgan | ExperienceAdapter;
+    hands?: HandsOrgan;
+    ear?: EarOrgan;
+    observation?: ObservationOrgan;
+    mouth?: MouthOrgan;
+    self?: SelfRepository;
+    externalKnowledge?: EKnowledgeOrgan;
+    actionStore?: ActionStore;
+    actionPolicy?: ActionPolicyEngine;
+}
+/**
+ * CompanionContainer manages the lifecycle, discovery, wiring, and dependency injection
+ * of organs and infrastructure for a companion instance.
+ */
+export declare class CompanionContainer {
+    readonly id: string;
+    readonly config: SiduriRuntimeConfig;
+    readonly organs: RuntimeOrgans;
+    readonly gating: ResponseGatingEngine;
+    readonly actionPolicy: ActionPolicyEngine;
+    readonly dispatcher: ExperienceDispatcher;
+    readonly sessionHistory: SessionHistoryManager;
+    private _runtime?;
+    constructor(id: string, config: SiduriRuntimeConfig, organs?: RuntimeOrgans);
+    get brain(): BrainOrgan | undefined;
+    get memory(): MemoryOrgan | undefined;
+    get voice(): ExperienceAdapter | VoiceOrgan | undefined;
+    get knowledge(): KnowledgeOrgan | undefined;
+    get vision(): VisionOrgan | undefined;
+    get behavior(): BehaviorOrgan | undefined;
+    get body(): ExperienceAdapter | BodyOrgan | undefined;
+    get hands(): HandsOrgan | undefined;
+    get ear(): EarOrgan | undefined;
+    get observation(): ObservationOrgan | undefined;
+    set observation(org: ObservationOrgan | undefined);
+    get mouth(): MouthOrgan | undefined;
+    get self(): SelfRepository | undefined;
+    get externalKnowledge(): EKnowledgeOrgan | undefined;
+    initialize(): Promise<void>;
+    get runtime(): SiduriRuntime;
+}

package/dist/container.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionContainer = void 0;
+const index_1 = require("./index");
+const session_history_1 = require("./session-history");
+const runtime_1 = require("./runtime");
+/**
+ * CompanionContainer manages the lifecycle, discovery, wiring, and dependency injection
+ * of organs and infrastructure for a companion instance.
+ */
+class CompanionContainer {
+    id;
+    config;
+    organs;
+    gating;
+    actionPolicy;
+    dispatcher;
+    sessionHistory;
+    _runtime;
+    constructor(id, config, organs = {}) {
+        this.id = id;
+        this.config = config;
+        this.organs = organs;
+        this.gating = new index_1.ResponseGatingEngine();
+        let actionStore = organs.actionStore;
+        if (!actionStore) {
+            const storeOpt = config.actionStore;
+            const storePath = config.actionStorePath || (typeof storeOpt === 'object' ? storeOpt.dbPath : undefined);
+            if (storeOpt === 'sqlite' || (typeof storeOpt === 'object' && storeOpt.type === 'sqlite') || storePath) {
+                actionStore = new index_1.SqliteActionStore({ dbPath: storePath });
+            }
+        }
+        this.actionPolicy = organs.actionPolicy || new index_1.ActionPolicyEngine({
+            store: actionStore,
+        });
+        this.dispatcher = new index_1.ExperienceDispatcher();
+        if (this.organs.voice && typeof this.organs.voice.handleEvent === 'function') {
+            this.dispatcher.registerAdapter(this.organs.voice);
+        }
+        if (this.organs.body && typeof this.organs.body.handleEvent === 'function') {
+            this.dispatcher.registerAdapter(this.organs.body);
+        }
+        if (this.organs.mouth && typeof this.organs.mouth.handleEvent === 'function') {
+            this.dispatcher.registerAdapter(this.organs.mouth);
+        }
+        this.sessionHistory = new session_history_1.SessionHistoryManager();
+    }
+    // Direct organ accessors
+    get brain() { return this.organs.brain; }
+    get memory() { return this.organs.memory; }
+    get voice() { return this.organs.voice; }
+    get knowledge() { return this.organs.knowledge; }
+    get vision() { return this.organs.vision; }
+    get behavior() { return this.organs.behavior; }
+    get body() { return this.organs.body; }
+    get hands() { return this.organs.hands; }
+    get ear() { return this.organs.ear; }
+    get observation() { return this.organs.observation; }
+    set observation(org) { this.organs.observation = org; }
+    get mouth() { return this.organs.mouth; }
+    get self() { return this.organs.self; }
+    get externalKnowledge() { return this.organs.externalKnowledge; }
+    async initialize() {
+        if (this.organs.memory && typeof this.organs.memory.initialize === 'function') {
+            await this.organs.memory.initialize(this.id);
+        }
+        if (this.organs.hands && typeof this.organs.hands.listTools === 'function') {
+            const tools = await this.organs.hands.listTools();
+            for (const tool of tools) {
+                this.actionPolicy.registerToolDefinition(tool);
+            }
+        }
+    }
+    get runtime() {
+        if (!this._runtime) {
+            this._runtime = new runtime_1.SiduriRuntime(this.id, this.config, this);
+        }
+        return this._runtime;
+    }
+}
+exports.CompanionContainer = CompanionContainer;

package/dist/context.d.ts

@@ -12,6 +12,7 @@ export interface ConversationContext {
     [key: string]: unknown;
 }
 export type SubjectKind = 'actor' | 'companion' | 'configured';
+export type InteractionMode = 'casual' | 'teach' | 'hybrid';
 export interface SubjectRef {
     subjectId: string;
     kind: SubjectKind;
@@ -23,9 +24,10 @@ export interface RequestContext {
     conversation: ConversationContext;
     source?: 'local' | 'external' | string;
     subject?: SubjectRef;
+    mode?: InteractionMode;
     metadata?: Record<string, unknown>;
 }
-export type DiagnosticCode = 'legacy_role_removed' | 'anonymous_session_generated' | 'companion_default_mapped_for_bootstrap' | 'actor_scoped_subject_mapped';
+export type DiagnosticCode = 'legacy_role_removed' | 'anonymous_session_generated' | 'companion_default_mapped_for_bootstrap' | 'actor_scoped_subject_mapped' | 'role_escalation_attempt_suppressed' | 'capability_escalation_attempt_suppressed';
 export type ContextErrorCode = 'MISSING_CONTEXT' | 'INVALID_CONTEXT' | 'FORBIDDEN_CONTEXT' | 'AMBIGUOUS_CONTEXT' | 'UNAUTHORIZED_CAPABILITY';
 export interface ContextError {
     code: ContextErrorCode;

package/dist/context.js

@@ -55,6 +55,19 @@ function validateRequestContext(context) {
             }
         }
     }
+    if (ctx.mode !== undefined) {
+        if (ctx.mode !== 'casual' && ctx.mode !== 'teach' && ctx.mode !== 'hybrid') {
+            return {
+                accepted: false,
+                error: {
+                    code: 'INVALID_CONTEXT',
+                    message: `Invalid interaction mode: '${ctx.mode}' (expected 'casual', 'teach', or 'hybrid')`,
+                    field: 'mode',
+                    correlationId: ctx.conversation?.correlationId,
+                },
+            };
+        }
+    }
     if (missingFields.length > 0) {
         return {
             accepted: false,

package/dist/index.d.ts

@@ -25,6 +25,8 @@ export * from './session-history';
 export * from './schema-validator';
 export * from './siduri-db';
 export * from './database';
+export * from './container';
+export * from './perception-pipeline';
 import { EvidenceRecord } from './evidence';
 import { ActionIntent } from './action';
 import { RequestContext } from './context';
@@ -253,19 +255,25 @@ export interface HealthProbeResult {
 }
 export type HealthProbeFn = (context: HealthProbeContext) => Promise<HealthProbeResult> | HealthProbeResult;
 export * from './mouth-types';
-import type { SelfIdentity, PersonalityTraits, SelfDirective, SelfRelationship, LifeInventoryItem, LifeScheduleItem, LifePreference, MemoryClaim, EpisodicEvent } from './siduri-db';
+import type { SelfIdentity, PersonalityTraits, SelfDirective, SelfRelationship, SelfDialogueExample, LifeInventoryItem, LifeScheduleItem, LifePreference, MemoryClaim, EpisodicEvent } from './siduri-db';
+export type { SelfIdentity, PersonalityTraits, SelfDirective, SelfRelationship, SelfDialogueExample, LifeInventoryItem, LifeScheduleItem, LifePreference, MemoryClaim, EpisodicEvent, };
 export interface SelfRepository {
     getIdentity(companionId: string): Promise<SelfIdentity | undefined>;
-    getPersonality(companionId: string): Promise<PersonalityTraits>;
+    getPersonality?(companionId: string): Promise<PersonalityTraits>;
     getActiveDirectives(companionId: string): Promise<SelfDirective[]>;
     getRelationship(companionId: string, entityId: string): Promise<SelfRelationship | null>;
+    getRelationships?(companionId: string): Promise<SelfRelationship[]>;
+    getExemplars?(companionId: string): Promise<SelfDialogueExample[]>;
+    setExemplars?(companionId: string, exemplars: SelfDialogueExample[]): Promise<void>;
     commitDirectives(companionId: string, directives: SelfDirective[]): Promise<void>;
     updateRelationship(companionId: string, rel: SelfRelationship): Promise<void>;
     disableDirective?(id: string): Promise<void>;
     getActiveSelf?(companionId: string): Promise<{
         identity?: SelfIdentity;
-        personality: PersonalityTraits;
+        personality?: PersonalityTraits;
         directives: SelfDirective[];
+        relationships?: SelfRelationship[];
+        exemplars?: SelfDialogueExample[];
     }>;
 }
 export interface LifeDatabase {

package/dist/index.js

@@ -42,5 +42,7 @@ __exportStar(require("./session-history"), exports);
 __exportStar(require("./schema-validator"), exports);
 __exportStar(require("./siduri-db"), exports);
 __exportStar(require("./database"), exports);
+__exportStar(require("./container"), exports);
+__exportStar(require("./perception-pipeline"), exports);
 // Mouth (Communication & Output Delivery)
 __exportStar(require("./mouth-types"), exports);

package/dist/input-normalizer.js

@@ -16,7 +16,9 @@ async function normalizeUserInput(message, roleOrContext = 'OWNER', history = []
     }
     const isContextObject = typeof roleOrContext === 'object' && roleOrContext !== null;
     const role = isContextObject
-        ? (roleOrContext.actor?.authorizationRole === 'viewer' ? 'VIEWER' : 'OWNER')
+        ? (roleOrContext.actor?.authorizationRole === 'viewer' || roleOrContext.actor?.authenticated === false
+            ? 'VIEWER'
+            : 'OWNER')
         : roleOrContext;
     const requestContext = isContextObject
         ? roleOrContext