silo-agent 1.0.0

package/build/lib/agent-router.d.ts

@@ -0,0 +1,110 @@
+/**
+ * SILO — Agent Router
+ *
+ * Enables any agent to dynamically spin up sub-agents with:
+ *   - Inherited shared memory context (via 0G root hashes)
+ *   - A dedicated parent↔child communication channel
+ *   - Configurable autonomy levels (supervised vs autonomous)
+ *   - Result propagation back to the parent
+ *
+ * The router manages a tree of agent relationships and their communication
+ * channels. Each sub-agent gets its own vault instance but shares memory
+ * context with its parent through 0G-backed channels.
+ *
+ * Communication Flow:
+ *   Parent spawns SubAgent → creates dedicated channel "agent:{parentId}:{childId}"
+ *   Parent writes context to channel → SubAgent reads on startup
+ *   SubAgent writes results to channel → Parent receives via subscription
+ *   SubAgent can itself spawn further sub-agents (recursive)
+ */
+import { AgentVault } from "./vault.js";
+import { SharedMemoryBus, type MemoryEntry } from "./shared-memory.js";
+export type AgentAutonomy = "supervised" | "autonomous";
+export type AgentStatus = "initializing" | "running" | "waiting" | "completed" | "failed" | "terminated";
+export interface SubAgentDescriptor {
+    id: string;
+    role: string;
+    parentId: string;
+    channelName: string;
+    status: AgentStatus;
+    autonomy: AgentAutonomy;
+    createdAt: number;
+    completedAt: number | null;
+    contextRootHashes: string[];
+    resultRootHash: string | null;
+    metadata?: Record<string, any>;
+}
+export interface SpawnOptions {
+    role: string;
+    contextRootHashes?: string[];
+    contextData?: string;
+    autonomy?: AgentAutonomy;
+    metadata?: Record<string, any>;
+    onMessage?: (entry: MemoryEntry) => void;
+    onComplete?: (result: SubAgentResult) => void;
+}
+export interface SubAgentResult {
+    agentId: string;
+    role: string;
+    success: boolean;
+    output: string;
+    rootHash: string | null;
+    duration: number;
+    eventsProcessed: number;
+}
+export interface AgentMessage {
+    type: "context" | "instruction" | "result" | "status" | "error";
+    from: string;
+    to: string;
+    payload: string;
+    timestamp: number;
+}
+export declare class AgentRouter {
+    private vault;
+    private sharedMemory;
+    private agentId;
+    private children;
+    private parentId;
+    private messageHandlers;
+    private onSpawn?;
+    private onMessage?;
+    constructor(vault: AgentVault, sharedMemory: SharedMemoryBus);
+    get id(): string;
+    /** Register handlers for external notifications (WebSocket, etc.) */
+    setEventHandlers(handlers: {
+        onSpawn?: (descriptor: SubAgentDescriptor) => void;
+        onMessage?: (channel: string, msg: AgentMessage) => void;
+    }): void;
+    /**
+     * Spawn a sub-agent with shared context.
+     *
+     * Creates a dedicated communication channel and seeds it with context.
+     * The sub-agent descriptor is returned immediately — the actual agent
+     * execution happens asynchronously (driven by whoever picks up the descriptor).
+     */
+    spawn(options: SpawnOptions): Promise<SubAgentDescriptor>;
+    /** Send a message to a sub-agent (or parent) via their shared channel */
+    sendMessage(channelName: string, message: AgentMessage): Promise<MemoryEntry>;
+    /** Send an instruction to a specific sub-agent */
+    instruct(childId: string, instruction: string): Promise<MemoryEntry>;
+    /** Report a result back to the parent (called by sub-agents) */
+    reportResult(result: SubAgentResult): Promise<void>;
+    /** Mark a sub-agent as completed */
+    completeChild(childId: string, resultRootHash?: string): void;
+    /** Terminate a sub-agent */
+    terminateChild(childId: string, reason?: string): Promise<void>;
+    /** Set this agent as a child of a parent */
+    setParent(parentId: string): void;
+    /** List all sub-agents */
+    listChildren(): SubAgentDescriptor[];
+    /** Get a sub-agent's descriptor */
+    getChild(childId: string): SubAgentDescriptor | undefined;
+    /** Get full agent tree status */
+    status(): {
+        agentId: string;
+        parentId: string | null;
+        childCount: number;
+        children: SubAgentDescriptor[];
+        channels: string[];
+    };
+}

package/build/lib/agent-router.js

@@ -0,0 +1,197 @@
+/**
+ * SILO — Agent Router
+ *
+ * Enables any agent to dynamically spin up sub-agents with:
+ *   - Inherited shared memory context (via 0G root hashes)
+ *   - A dedicated parent↔child communication channel
+ *   - Configurable autonomy levels (supervised vs autonomous)
+ *   - Result propagation back to the parent
+ *
+ * The router manages a tree of agent relationships and their communication
+ * channels. Each sub-agent gets its own vault instance but shares memory
+ * context with its parent through 0G-backed channels.
+ *
+ * Communication Flow:
+ *   Parent spawns SubAgent → creates dedicated channel "agent:{parentId}:{childId}"
+ *   Parent writes context to channel → SubAgent reads on startup
+ *   SubAgent writes results to channel → Parent receives via subscription
+ *   SubAgent can itself spawn further sub-agents (recursive)
+ */
+import { createHash } from "node:crypto";
+export class AgentRouter {
+    vault;
+    sharedMemory;
+    agentId;
+    children = new Map();
+    parentId = null;
+    messageHandlers = new Map();
+    onSpawn;
+    onMessage;
+    constructor(vault, sharedMemory) {
+        this.vault = vault;
+        this.sharedMemory = sharedMemory;
+        this.agentId = vault.address;
+    }
+    get id() { return this.agentId; }
+    /** Register handlers for external notifications (WebSocket, etc.) */
+    setEventHandlers(handlers) {
+        this.onSpawn = handlers.onSpawn;
+        this.onMessage = handlers.onMessage;
+    }
+    /**
+     * Spawn a sub-agent with shared context.
+     *
+     * Creates a dedicated communication channel and seeds it with context.
+     * The sub-agent descriptor is returned immediately — the actual agent
+     * execution happens asynchronously (driven by whoever picks up the descriptor).
+     */
+    async spawn(options) {
+        const childId = createHash("sha256")
+            .update(`subagent:${this.agentId}:${options.role}:${Date.now()}:${Math.random()}`)
+            .digest("hex")
+            .slice(0, 16);
+        const channelName = `agent:${this.agentId.slice(0, 8)}:${childId}`;
+        this.sharedMemory.createChannel(channelName);
+        const descriptor = {
+            id: childId,
+            role: options.role,
+            parentId: this.agentId,
+            channelName,
+            status: "initializing",
+            autonomy: options.autonomy ?? "supervised",
+            createdAt: Date.now(),
+            completedAt: null,
+            contextRootHashes: options.contextRootHashes ?? [],
+            resultRootHash: null,
+            metadata: options.metadata,
+        };
+        this.children.set(childId, descriptor);
+        if (options.contextData) {
+            await this.sendMessage(channelName, {
+                type: "context",
+                from: this.agentId,
+                to: childId,
+                payload: options.contextData,
+                timestamp: Date.now(),
+            });
+        }
+        if (options.contextRootHashes?.length) {
+            await this.sendMessage(channelName, {
+                type: "context",
+                from: this.agentId,
+                to: childId,
+                payload: JSON.stringify({
+                    inheritedMemory: options.contextRootHashes,
+                    instruction: "Retrieve these root hashes from 0G to load shared context",
+                }),
+                timestamp: Date.now(),
+            });
+        }
+        if (options.onMessage) {
+            this.sharedMemory.subscribe(channelName, (entry) => {
+                try {
+                    const msg = JSON.parse(entry.data);
+                    if (msg.from !== this.agentId) {
+                        options.onMessage(entry);
+                    }
+                }
+                catch { }
+            });
+        }
+        descriptor.status = "running";
+        this.onSpawn?.(descriptor);
+        const descriptorData = JSON.stringify(descriptor);
+        const stored = await this.vault.store(descriptorData, `spawn:${options.role}`);
+        await this.sharedMemory.write("silo:agents", JSON.stringify({
+            event: "agent_spawned",
+            descriptor: { ...descriptor, storedAt: stored.rootHash },
+        }));
+        return descriptor;
+    }
+    /** Send a message to a sub-agent (or parent) via their shared channel */
+    async sendMessage(channelName, message) {
+        const entry = await this.sharedMemory.write(channelName, JSON.stringify(message), {
+            messageType: message.type,
+            from: message.from,
+            to: message.to,
+        });
+        this.onMessage?.(channelName, message);
+        return entry;
+    }
+    /** Send an instruction to a specific sub-agent */
+    async instruct(childId, instruction) {
+        const child = this.children.get(childId);
+        if (!child)
+            throw new Error(`Sub-agent "${childId}" not found`);
+        return this.sendMessage(child.channelName, {
+            type: "instruction",
+            from: this.agentId,
+            to: childId,
+            payload: instruction,
+            timestamp: Date.now(),
+        });
+    }
+    /** Report a result back to the parent (called by sub-agents) */
+    async reportResult(result) {
+        if (!this.parentId)
+            return;
+        const channelName = `agent:${this.parentId.slice(0, 8)}:${this.agentId.slice(0, 16)}`;
+        const stored = await this.vault.store(JSON.stringify(result), `result:${result.role}`);
+        await this.sendMessage(channelName, {
+            type: "result",
+            from: this.agentId,
+            to: this.parentId,
+            payload: JSON.stringify({ ...result, rootHash: stored.rootHash }),
+            timestamp: Date.now(),
+        });
+    }
+    /** Mark a sub-agent as completed */
+    completeChild(childId, resultRootHash) {
+        const child = this.children.get(childId);
+        if (!child)
+            return;
+        child.status = "completed";
+        child.completedAt = Date.now();
+        if (resultRootHash)
+            child.resultRootHash = resultRootHash;
+    }
+    /** Terminate a sub-agent */
+    async terminateChild(childId, reason) {
+        const child = this.children.get(childId);
+        if (!child)
+            return;
+        await this.sendMessage(child.channelName, {
+            type: "instruction",
+            from: this.agentId,
+            to: childId,
+            payload: JSON.stringify({ action: "terminate", reason }),
+            timestamp: Date.now(),
+        });
+        child.status = "terminated";
+        child.completedAt = Date.now();
+    }
+    /** Set this agent as a child of a parent */
+    setParent(parentId) {
+        this.parentId = parentId;
+    }
+    /** List all sub-agents */
+    listChildren() {
+        return Array.from(this.children.values());
+    }
+    /** Get a sub-agent's descriptor */
+    getChild(childId) {
+        return this.children.get(childId);
+    }
+    /** Get full agent tree status */
+    status() {
+        const channels = Array.from(this.children.values()).map(c => c.channelName);
+        return {
+            agentId: this.agentId,
+            parentId: this.parentId,
+            childCount: this.children.size,
+            children: this.listChildren(),
+            channels,
+        };
+    }
+}
+//# sourceMappingURL=agent-router.js.map

package/build/lib/agent-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-router.js","sourceRoot":"","sources":["../../src/lib/agent-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA+CzC,MAAM,OAAO,WAAW;IACd,KAAK,CAAa;IAClB,YAAY,CAAkB;IAC9B,OAAO,CAAS;IAChB,QAAQ,GAAoC,IAAI,GAAG,EAAE,CAAC;IACtD,QAAQ,GAAkB,IAAI,CAAC;IAC/B,eAAe,GAA6C,IAAI,GAAG,EAAE,CAAC;IAEtE,OAAO,CAA4C;IACnD,SAAS,CAAgD;IAEjE,YAAY,KAAiB,EAAE,YAA6B;QAC1D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC/B,CAAC;IAED,IAAI,EAAE,KAAa,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAEzC,qEAAqE;IACrE,gBAAgB,CAAC,QAGhB;QACC,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC;IACtC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,OAAqB;QAC/B,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC;aACjC,MAAM,CAAC,YAAY,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;aACjF,MAAM,CAAC,KAAK,CAAC;aACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAEhB,MAAM,WAAW,GAAG,SAAS,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;QACnE,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;QAE7C,MAAM,UAAU,GAAuB;YACrC,EAAE,EAAE,OAAO;YACX,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,QAAQ,EAAE,IAAI,CAAC,OAAO;YACtB,WAAW;YACX,MAAM,EAAE,cAAc;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,YAAY;YAC1C,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,WAAW,EAAE,IAAI;YACjB,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,IAAI,EAAE;YAClD,cAAc,EAAE,IAAI;YACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC;QAEF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAEvC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE;gBAClC,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,IAAI,CAAC,OAAO;gBAClB,EAAE,EAAE,OAAO;gBACX,OAAO,EAAE,OAAO,CAAC,WAAW;gBAC5B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;aACtB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,OAAO,CAAC,iBAAiB,EAAE,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE;gBAClC,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,IAAI,CAAC,OAAO;gBAClB,EAAE,EAAE,OAAO;gBACX,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC;oBACtB,eAAe,EAAE,OAAO,CAAC,iBAAiB;oBAC1C,WAAW,EAAE,2DAA2D;iBACzE,CAAC;gBACF,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;aACtB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE;gBACjD,IAAI,CAAC;oBACH,MAAM,GAAG,GAAiB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACjD,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;wBAC9B,OAAO,CAAC,SAAU,CAAC,KAAK,CAAC,CAAC;oBAC5B,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC,CAAA,CAAC;YACZ,CAAC,CAAC,CAAC;QACL,CAAC;QAED,UAAU,CAAC,MAAM,GAAG,SAAS,CAAC;QAC9B,IAAI,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC,CAAC;QAE3B,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,SAAS,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAE/E,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC;YAC1D,KAAK,EAAE,eAAe;YACtB,UAAU,EAAE,EAAE,GAAG,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;SACzD,CAAC,CAAC,CAAC;QAEJ,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,WAAW,CAAC,WAAmB,EAAE,OAAqB;QAC1D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE;YAChF,WAAW,EAAE,OAAO,CAAC,IAAI;YACzB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,EAAE,EAAE,OAAO,CAAC,EAAE;SACf,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,QAAQ,CAAC,OAAe,EAAE,WAAmB;QACjD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,cAAc,OAAO,aAAa,CAAC,CAAC;QAEhE,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,WAAW,EAAE;YACzC,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,IAAI,CAAC,OAAO;YAClB,EAAE,EAAE,OAAO;YACX,OAAO,EAAE,WAAW;YACpB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,YAAY,CAAC,MAAsB;QACvC,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAE3B,MAAM,WAAW,GAAG,SAAS,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;QAEtF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAEvF,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE;YAClC,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,IAAI,CAAC,OAAO;YAClB,EAAE,EAAE,IAAI,CAAC,QAAQ;YACjB,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;YACjE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED,oCAAoC;IACpC,aAAa,CAAC,OAAe,EAAE,cAAuB;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC;QAC3B,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC/B,IAAI,cAAc;YAAE,KAAK,CAAC,cAAc,GAAG,cAAc,CAAC;IAC5D,CAAC;IAED,4BAA4B;IAC5B,KAAK,CAAC,cAAc,CAAC,OAAe,EAAE,MAAe;QACnD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK;YAAE,OAAO;QAEnB,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,WAAW,EAAE;YACxC,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,IAAI,CAAC,OAAO;YAClB,EAAE,EAAE,OAAO;YACX,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;YACxD,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;QAEH,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC;QAC5B,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACjC,CAAC;IAED,4CAA4C;IAC5C,SAAS,CAAC,QAAgB;QACxB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,0BAA0B;IAC1B,YAAY;QACV,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,mCAAmC;IACnC,QAAQ,CAAC,OAAe;QACtB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,iCAAiC;IACjC,MAAM;QAOJ,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QAC5E,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;YAC9B,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE;YAC7B,QAAQ;SACT,CAAC;IACJ,CAAC;CACF"}

package/build/lib/attestation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 0G Agent Shield — Attestation Layer
+ *
+ * Tracks every action an agent takes during a session:
+ *   - What was stored (hash of plaintext, NOT the plaintext)
+ *   - What was retrieved
+ *   - What tools were called
+ *
+ * At session end, builds a Merkle root from all event hashes.
+ * The full encrypted trace goes to 0G Storage.
+ * The Merkle root is the public commitment — anyone can verify
+ * "this agent did N things in this session" without seeing what.
+ *
+ * This is what makes 0g-agent-shield more than an encrypted storage wrapper.
+ * It's verifiable agent behavior.
+ */
+export interface AttestationEvent {
+    type: "store" | "retrieve" | "tool_call" | "policy_check";
+    timestamp: number;
+    inputHash: string;
+    outputHash: string;
+    metadata?: string;
+}
+export interface SessionAttestation {
+    sessionId: string;
+    agentAddress: string;
+    startedAt: number;
+    endedAt: number;
+    eventCount: number;
+    merkleRoot: string;
+    events: AttestationEvent[];
+}
+export declare class AttestationSession {
+    private events;
+    private sessionId;
+    private agentAddress;
+    private startedAt;
+    constructor(agentAddress: string);
+    get id(): string;
+    get count(): number;
+    /**
+     * Record an agent action. Only hashes are stored in the event —
+     * the actual content is never part of the attestation.
+     */
+    record(type: AttestationEvent["type"], input: string, output: string, metadata?: string): AttestationEvent;
+    /**
+     * Build a Merkle root from all recorded events.
+     * Uses simple pairwise SHA-256 hashing.
+     *
+     * This root is the public commitment: it proves exactly how many
+     * actions occurred and their order, without revealing content.
+     */
+    computeMerkleRoot(): string;
+    /**
+     * Finalize the session and produce the attestation record.
+     * This gets encrypted and stored on 0G.
+     * The merkleRoot is the only thing that needs to be public.
+     */
+    finalize(): SessionAttestation;
+    /**
+     * Produce a human-readable summary (for CLI/demo output).
+     */
+    summary(): string;
+}

package/build/lib/attestation.js

@@ -0,0 +1,112 @@
+/**
+ * 0G Agent Shield — Attestation Layer
+ *
+ * Tracks every action an agent takes during a session:
+ *   - What was stored (hash of plaintext, NOT the plaintext)
+ *   - What was retrieved
+ *   - What tools were called
+ *
+ * At session end, builds a Merkle root from all event hashes.
+ * The full encrypted trace goes to 0G Storage.
+ * The Merkle root is the public commitment — anyone can verify
+ * "this agent did N things in this session" without seeing what.
+ *
+ * This is what makes 0g-agent-shield more than an encrypted storage wrapper.
+ * It's verifiable agent behavior.
+ */
+import { createHash } from "node:crypto";
+export class AttestationSession {
+    events = [];
+    sessionId;
+    agentAddress;
+    startedAt;
+    constructor(agentAddress) {
+        this.agentAddress = agentAddress;
+        this.startedAt = Date.now();
+        this.sessionId = createHash("sha256")
+            .update(`${agentAddress}-${this.startedAt}-${Math.random()}`)
+            .digest("hex")
+            .slice(0, 16);
+    }
+    get id() {
+        return this.sessionId;
+    }
+    get count() {
+        return this.events.length;
+    }
+    /**
+     * Record an agent action. Only hashes are stored in the event —
+     * the actual content is never part of the attestation.
+     */
+    record(type, input, output, metadata) {
+        const event = {
+            type,
+            timestamp: Date.now(),
+            inputHash: createHash("sha256").update(input).digest("hex"),
+            outputHash: createHash("sha256").update(output).digest("hex"),
+            metadata,
+        };
+        this.events.push(event);
+        return event;
+    }
+    /**
+     * Build a Merkle root from all recorded events.
+     * Uses simple pairwise SHA-256 hashing.
+     *
+     * This root is the public commitment: it proves exactly how many
+     * actions occurred and their order, without revealing content.
+     */
+    computeMerkleRoot() {
+        if (this.events.length === 0) {
+            return createHash("sha256").update("empty-session").digest("hex");
+        }
+        // Leaf nodes: hash of each event's combined hashes
+        let leaves = this.events.map((e) => createHash("sha256")
+            .update(`${e.type}:${e.inputHash}:${e.outputHash}:${e.timestamp}`)
+            .digest("hex"));
+        // Build tree bottom-up
+        while (leaves.length > 1) {
+            const next = [];
+            for (let i = 0; i < leaves.length; i += 2) {
+                const left = leaves[i];
+                const right = leaves[i + 1] ?? left; // duplicate last if odd
+                next.push(createHash("sha256").update(left + right).digest("hex"));
+            }
+            leaves = next;
+        }
+        return leaves[0];
+    }
+    /**
+     * Finalize the session and produce the attestation record.
+     * This gets encrypted and stored on 0G.
+     * The merkleRoot is the only thing that needs to be public.
+     */
+    finalize() {
+        return {
+            sessionId: this.sessionId,
+            agentAddress: this.agentAddress,
+            startedAt: this.startedAt,
+            endedAt: Date.now(),
+            eventCount: this.events.length,
+            merkleRoot: this.computeMerkleRoot(),
+            events: [...this.events], // copy
+        };
+    }
+    /**
+     * Produce a human-readable summary (for CLI/demo output).
+     */
+    summary() {
+        const root = this.computeMerkleRoot();
+        const lines = [
+            `Session: ${this.sessionId}`,
+            `Agent:   ${this.agentAddress.slice(0, 10)}...`,
+            `Events:  ${this.events.length}`,
+            `Root:    ${root.slice(0, 16)}...`,
+            "",
+            "Event Log:",
+            ...this.events.map((e, i) => `  ${i + 1}. [${e.type}] ${new Date(e.timestamp).toISOString()} — ${e.metadata ?? ""}`),
+        ];
+        return lines.join("\n");
+    }
+}
+//# sourceMappingURL=attestation.js.map

package/build/lib/attestation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.js","sourceRoot":"","sources":["../../src/lib/attestation.ts"],"names":[],"mappings":"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"}

package/build/lib/autonomy.d.ts

@@ -0,0 +1,116 @@
+/**
+ * SILO — Autonomy Engine
+ *
+ * The orchestrator that ties heartbeat + shared memory + agent routing into
+ * a fully autonomous build pipeline.
+ *
+ * When enabled, the engine:
+ *   1. Monitors the system via heartbeat tasks
+ *   2. Detects issues through diagnostic handlers
+ *   3. Spawns sub-agents to investigate and fix problems
+ *   4. Pushes fixes through the attestation pipeline
+ *   5. Persists all decisions and outcomes to shared memory on 0G
+ *
+ * The autonomy loop:
+ *   DETECT → PLAN → SPAWN → FIX → ATTEST → REPEAT
+ *
+ * All autonomous actions are fully attested — the Merkle tree captures
+ * every decision, fix, and outcome. Nothing happens in the dark.
+ */
+import { AgentVault } from "./vault.js";
+import { SharedMemoryBus } from "./shared-memory.js";
+import { HeartbeatDaemon, type TaskContext } from "./heartbeat.js";
+import { AgentRouter } from "./agent-router.js";
+export type AutonomyLevel = "off" | "monitor" | "suggest" | "autonomous";
+export interface AutonomyConfig {
+    level: AutonomyLevel;
+    heartbeatIntervalMs: number;
+    fixChannel: string;
+    decisionChannel: string;
+    maxConcurrentAgents: number;
+    autoCommitIntervalMs: number;
+    diagnosticHandlers: DiagnosticHandler[];
+    onDecision?: (decision: AutonomyDecision) => void;
+    onFixPushed?: (fix: AutonomyFix) => void;
+}
+export interface DiagnosticHandler {
+    name: string;
+    description: string;
+    check: (ctx: TaskContext) => Promise<DiagnosticResult>;
+    fix?: (ctx: TaskContext, diagnostic: DiagnosticResult) => Promise<FixResult>;
+}
+export interface DiagnosticResult {
+    handler: string;
+    healthy: boolean;
+    severity: "info" | "warning" | "critical";
+    message: string;
+    details?: Record<string, any>;
+    suggestedFix?: string;
+}
+export interface FixResult {
+    applied: boolean;
+    description: string;
+    rootHash?: string;
+    rollbackData?: string;
+}
+export interface AutonomyDecision {
+    id: string;
+    timestamp: number;
+    trigger: string;
+    diagnostic: DiagnosticResult;
+    action: "ignore" | "log" | "suggest" | "auto_fix" | "spawn_agent";
+    reasoning: string;
+    autonomyLevel: AutonomyLevel;
+}
+export interface AutonomyFix {
+    id: string;
+    decisionId: string;
+    timestamp: number;
+    handler: string;
+    result: FixResult;
+    attestedRootHash: string | null;
+    agentId: string | null;
+}
+export declare class AutonomyEngine {
+    private vault;
+    private sharedMemory;
+    private heartbeat;
+    private router;
+    private config;
+    private decisions;
+    private fixes;
+    private running;
+    private diagnosticTimer;
+    constructor(vault: AgentVault, sharedMemory: SharedMemoryBus, heartbeat: HeartbeatDaemon, router: AgentRouter, config?: Partial<AutonomyConfig>);
+    get level(): AutonomyLevel;
+    get isRunning(): boolean;
+    /** Set autonomy level at runtime */
+    setLevel(level: AutonomyLevel): void;
+    /** Register a diagnostic handler */
+    registerDiagnostic(handler: DiagnosticHandler): void;
+    /**
+     * Start the autonomy engine.
+     * Initializes shared memory channels, starts heartbeat, and begins diagnostic loop.
+     */
+    start(): void;
+    /** Stop the autonomy engine and all sub-systems */
+    stop(): void;
+    /** Run all registered diagnostic handlers and take action based on autonomy level */
+    private runDiagnostics;
+    /** Decide what to do about an unhealthy diagnostic based on autonomy level */
+    private handleDiagnostic;
+    /** Apply a fix directly */
+    private applyFix;
+    /** Spawn a dedicated sub-agent for critical issues */
+    private spawnFixAgent;
+    /** Get the full autonomy engine status */
+    status(): {
+        level: AutonomyLevel;
+        running: boolean;
+        heartbeat: ReturnType<HeartbeatDaemon["status"]>;
+        agents: ReturnType<AgentRouter["status"]>;
+        recentDecisions: AutonomyDecision[];
+        recentFixes: AutonomyFix[];
+        diagnosticHandlers: string[];
+    };
+}