silo-agent 1.0.0

package/build/lib/memory-index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * SILO — Memory Index
+ *
+ * A searchable catalog of everything stored on 0G through SILO.
+ * Solves the "I have a root hash but what IS it?" problem.
+ *
+ * Every store/write operation registers an entry in the index with:
+ *   - The root hash (the 0G address)
+ *   - Human-readable label
+ *   - Tags for categorization
+ *   - The channel it belongs to (if any)
+ *   - Who stored it and when
+ *   - Content type and size
+ *
+ * Agents can then SEARCH the index by label, tag, channel, author,
+ * or time range — no need to know root hashes in advance.
+ *
+ * The index itself is periodically snapshotted to 0G for durability.
+ * On startup, agents can load a snapshot to rebuild their local index.
+ */
+export interface IndexEntry {
+    rootHash: string;
+    label: string;
+    tags: string[];
+    channel: string | null;
+    authorId: string;
+    contentType: "data" | "shared_memory" | "attestation_trace" | "snapshot" | "agent_descriptor" | "fix_record" | "heartbeat";
+    size: number;
+    createdAt: number;
+    contentHash: string;
+    description?: string;
+    expiresAt?: number;
+    metadata?: Record<string, any>;
+}
+export interface SearchQuery {
+    label?: string;
+    tags?: string[];
+    channel?: string;
+    authorId?: string;
+    contentType?: IndexEntry["contentType"];
+    fromTime?: number;
+    toTime?: number;
+    limit?: number;
+}
+export interface IndexSnapshot {
+    snapshotAt: number;
+    entryCount: number;
+    entries: IndexEntry[];
+    schemaVersion: number;
+}
+export declare class MemoryIndex {
+    private entries;
+    private tagIndex;
+    private channelIndex;
+    private labelIndex;
+    private authorIndex;
+    /** Register a new entry in the index */
+    register(entry: IndexEntry): void;
+    /** Look up a single entry by root hash */
+    lookup(rootHash: string): IndexEntry | undefined;
+    /** Search the index with flexible query parameters */
+    search(query: SearchQuery): IndexEntry[];
+    /** Get all unique tags in the index */
+    allTags(): string[];
+    /** Get all entries for a specific channel, ordered by time */
+    channelEntries(channel: string): IndexEntry[];
+    /** Get summary statistics */
+    stats(): {
+        totalEntries: number;
+        uniqueTags: number;
+        uniqueChannels: number;
+        uniqueAuthors: number;
+        byContentType: Record<string, number>;
+    };
+    /** Export the full index as a snapshot (for persisting to 0G) */
+    exportSnapshot(): IndexSnapshot;
+    /** Import a snapshot (for restoring from 0G) */
+    importSnapshot(snapshot: IndexSnapshot): number;
+    /** Remove expired entries */
+    pruneExpired(): number;
+    private removeEntry;
+    get size(): number;
+}

package/build/lib/memory-index.js

@@ -0,0 +1,209 @@
+/**
+ * SILO — Memory Index
+ *
+ * A searchable catalog of everything stored on 0G through SILO.
+ * Solves the "I have a root hash but what IS it?" problem.
+ *
+ * Every store/write operation registers an entry in the index with:
+ *   - The root hash (the 0G address)
+ *   - Human-readable label
+ *   - Tags for categorization
+ *   - The channel it belongs to (if any)
+ *   - Who stored it and when
+ *   - Content type and size
+ *
+ * Agents can then SEARCH the index by label, tag, channel, author,
+ * or time range — no need to know root hashes in advance.
+ *
+ * The index itself is periodically snapshotted to 0G for durability.
+ * On startup, agents can load a snapshot to rebuild their local index.
+ */
+export class MemoryIndex {
+    entries = new Map();
+    tagIndex = new Map();
+    channelIndex = new Map();
+    labelIndex = new Map();
+    authorIndex = new Map();
+    /** Register a new entry in the index */
+    register(entry) {
+        this.entries.set(entry.rootHash, entry);
+        for (const tag of entry.tags) {
+            if (!this.tagIndex.has(tag))
+                this.tagIndex.set(tag, new Set());
+            this.tagIndex.get(tag).add(entry.rootHash);
+        }
+        if (entry.channel) {
+            if (!this.channelIndex.has(entry.channel))
+                this.channelIndex.set(entry.channel, new Set());
+            this.channelIndex.get(entry.channel).add(entry.rootHash);
+        }
+        const labelLower = entry.label.toLowerCase();
+        if (!this.labelIndex.has(labelLower))
+            this.labelIndex.set(labelLower, new Set());
+        this.labelIndex.get(labelLower).add(entry.rootHash);
+        if (!this.authorIndex.has(entry.authorId))
+            this.authorIndex.set(entry.authorId, new Set());
+        this.authorIndex.get(entry.authorId).add(entry.rootHash);
+    }
+    /** Look up a single entry by root hash */
+    lookup(rootHash) {
+        return this.entries.get(rootHash);
+    }
+    /** Search the index with flexible query parameters */
+    search(query) {
+        let candidateHashes = null;
+        if (query.tags?.length) {
+            const tagSets = query.tags
+                .map(t => this.tagIndex.get(t))
+                .filter((s) => !!s);
+            if (tagSets.length > 0) {
+                candidateHashes = intersectSets(tagSets);
+            }
+            else {
+                return [];
+            }
+        }
+        if (query.channel) {
+            const channelSet = this.channelIndex.get(query.channel);
+            if (!channelSet)
+                return [];
+            candidateHashes = candidateHashes ? intersectSets([candidateHashes, channelSet]) : new Set(channelSet);
+        }
+        if (query.authorId) {
+            const authorSet = this.authorIndex.get(query.authorId);
+            if (!authorSet)
+                return [];
+            candidateHashes = candidateHashes ? intersectSets([candidateHashes, authorSet]) : new Set(authorSet);
+        }
+        if (query.label) {
+            const labelLower = query.label.toLowerCase();
+            const exactMatch = this.labelIndex.get(labelLower);
+            if (exactMatch) {
+                candidateHashes = candidateHashes ? intersectSets([candidateHashes, exactMatch]) : new Set(exactMatch);
+            }
+            else {
+                const fuzzyMatches = new Set();
+                for (const [label, hashes] of this.labelIndex) {
+                    if (label.includes(labelLower)) {
+                        for (const h of hashes)
+                            fuzzyMatches.add(h);
+                    }
+                }
+                if (fuzzyMatches.size === 0)
+                    return [];
+                candidateHashes = candidateHashes ? intersectSets([candidateHashes, fuzzyMatches]) : fuzzyMatches;
+            }
+        }
+        let results;
+        if (candidateHashes) {
+            results = Array.from(candidateHashes)
+                .map(h => this.entries.get(h))
+                .filter((e) => !!e);
+        }
+        else {
+            results = Array.from(this.entries.values());
+        }
+        if (query.contentType) {
+            results = results.filter(e => e.contentType === query.contentType);
+        }
+        if (query.fromTime) {
+            results = results.filter(e => e.createdAt >= query.fromTime);
+        }
+        if (query.toTime) {
+            results = results.filter(e => e.createdAt <= query.toTime);
+        }
+        results.sort((a, b) => b.createdAt - a.createdAt);
+        const limit = query.limit ?? 50;
+        return results.slice(0, limit);
+    }
+    /** Get all unique tags in the index */
+    allTags() {
+        return Array.from(this.tagIndex.keys()).sort();
+    }
+    /** Get all entries for a specific channel, ordered by time */
+    channelEntries(channel) {
+        const hashes = this.channelIndex.get(channel);
+        if (!hashes)
+            return [];
+        return Array.from(hashes)
+            .map(h => this.entries.get(h))
+            .filter((e) => !!e)
+            .sort((a, b) => a.createdAt - b.createdAt);
+    }
+    /** Get summary statistics */
+    stats() {
+        const byContentType = {};
+        for (const entry of this.entries.values()) {
+            byContentType[entry.contentType] = (byContentType[entry.contentType] ?? 0) + 1;
+        }
+        return {
+            totalEntries: this.entries.size,
+            uniqueTags: this.tagIndex.size,
+            uniqueChannels: this.channelIndex.size,
+            uniqueAuthors: this.authorIndex.size,
+            byContentType,
+        };
+    }
+    /** Export the full index as a snapshot (for persisting to 0G) */
+    exportSnapshot() {
+        return {
+            snapshotAt: Date.now(),
+            entryCount: this.entries.size,
+            entries: Array.from(this.entries.values()),
+            schemaVersion: 1,
+        };
+    }
+    /** Import a snapshot (for restoring from 0G) */
+    importSnapshot(snapshot) {
+        let imported = 0;
+        for (const entry of snapshot.entries) {
+            if (!this.entries.has(entry.rootHash)) {
+                this.register(entry);
+                imported++;
+            }
+        }
+        return imported;
+    }
+    /** Remove expired entries */
+    pruneExpired() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [rootHash, entry] of this.entries) {
+            if (entry.expiresAt && entry.expiresAt <= now) {
+                this.removeEntry(rootHash);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+    removeEntry(rootHash) {
+        const entry = this.entries.get(rootHash);
+        if (!entry)
+            return;
+        this.entries.delete(rootHash);
+        for (const tag of entry.tags) {
+            this.tagIndex.get(tag)?.delete(rootHash);
+        }
+        if (entry.channel) {
+            this.channelIndex.get(entry.channel)?.delete(rootHash);
+        }
+        this.labelIndex.get(entry.label.toLowerCase())?.delete(rootHash);
+        this.authorIndex.get(entry.authorId)?.delete(rootHash);
+    }
+    get size() { return this.entries.size; }
+}
+function intersectSets(sets) {
+    if (sets.length === 0)
+        return new Set();
+    if (sets.length === 1)
+        return new Set(sets[0]);
+    const [smallest, ...rest] = [...sets].sort((a, b) => a.size - b.size);
+    const result = new Set();
+    for (const item of smallest) {
+        if (rest.every(s => s.has(item))) {
+            result.add(item);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=memory-index.js.map

package/build/lib/memory-index.js.map

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

package/build/lib/shared-memory.d.ts

@@ -0,0 +1,165 @@
+/**
+ * SILO — Shared Memory Bus
+ *
+ * Named channels backed by 0G Storage for real-time multi-agent communication.
+ *
+ * Design:
+ *   - Each channel is a linked list of entries on 0G (each entry points to the previous via rootHash)
+ *   - A coordinator layer provides channel locks and optimistic concurrency control
+ *   - A memory index provides root hash discoverability (search by label, tag, channel, author)
+ *   - Periodic snapshots persist the full channel state to 0G for crash recovery
+ *   - Any agent can create, join, write to, or read from a channel
+ *
+ * Safe Write Protocol (when coordinator is attached):
+ *   1. acquireLock(channel) → lockToken
+ *   2. Read current head → {headRootHash, version}
+ *   3. Upload to 0G with prevRootHash = headRootHash
+ *   4. commitWrite(channel, newRootHash, version, lockToken)
+ *   5. Coordinator validates → updates head → releases lock → broadcasts
+ *
+ * Without coordinator, writes are best-effort (backward compatible with v1).
+ */
+import { AgentVault } from "./vault.js";
+import { MemoryCoordinator, type ConflictError, type LockError } from "./memory-coordinator.js";
+import { MemoryIndex, type IndexEntry } from "./memory-index.js";
+export interface MemoryEntry {
+    id: string;
+    channel: string;
+    authorId: string;
+    timestamp: number;
+    data: string;
+    rootHash: string;
+    prevRootHash: string | null;
+    contentHash: string;
+    version: number;
+    metadata?: Record<string, any>;
+}
+export interface ChannelManifest {
+    name: string;
+    createdAt: number;
+    createdBy: string;
+    headRootHash: string | null;
+    version: number;
+    entryCount: number;
+    subscribers: string[];
+    snapshotRootHash: string | null;
+    lastSnapshotAt: number | null;
+    schema?: ChannelSchema;
+}
+export interface ChannelSchema {
+    description: string;
+    contentType?: string;
+    tags?: string[];
+    writableBy?: string[];
+}
+export interface ChannelSubscription {
+    channel: string;
+    agentId: string;
+    callback: (entry: MemoryEntry) => void;
+}
+export interface SharedMemoryConfig {
+    snapshotThreshold: number;
+    useCoordinator: boolean;
+    maxWriteRetries: number;
+}
+export type WriteResult = {
+    ok: true;
+    entry: MemoryEntry;
+} | {
+    ok: false;
+    error: ConflictError | LockError | {
+        code: "ERROR";
+        message: string;
+    };
+};
+export declare class SharedMemoryBus {
+    private vault;
+    private coordinator;
+    private index;
+    private channels;
+    private entries;
+    private subscriptions;
+    private config;
+    private agentId;
+    private onBroadcast?;
+    constructor(vault: AgentVault, config?: Partial<SharedMemoryConfig>);
+    /** Attach a coordinator for multi-agent safety (run on the API server) */
+    attachCoordinator(coordinator: MemoryCoordinator): void;
+    /** Get the memory index (for search, lookup, stats) */
+    getIndex(): MemoryIndex;
+    /** Get the coordinator (if attached) */
+    getCoordinator(): MemoryCoordinator | null;
+    /** Register a broadcast handler (e.g., Socket.IO emitter) for cross-process notifications */
+    setBroadcastHandler(handler: (channel: string, entry: MemoryEntry) => void): void;
+    /**
+     * Create a new named channel with optional schema.
+     * If the channel already exists, returns the existing manifest.
+     */
+    createChannel(name: string, schema?: ChannelSchema): ChannelManifest;
+    /** Subscribe to a channel. Callback fires on every new entry. */
+    subscribe(channel: string, callback: (entry: MemoryEntry) => void): ChannelSubscription;
+    /** Unsubscribe from a channel */
+    unsubscribe(subscription: ChannelSubscription): void;
+    /**
+     * Write data to a channel with coordination.
+     *
+     * When a coordinator is attached:
+     *   1. Acquires channel lock
+     *   2. Reads current head + version
+     *   3. Uploads to 0G with correct prevRootHash
+     *   4. Commits via coordinator (validates version)
+     *   5. Retries on conflict up to maxWriteRetries
+     *
+     * Without coordinator: best-effort write (v1 behavior).
+     */
+    write(channel: string, data: string, metadata?: Record<string, any>): Promise<MemoryEntry>;
+    /**
+     * Safe write with full coordination — locks, version checks, conflict retry.
+     */
+    private coordinatedWrite;
+    /** Best-effort write without coordination (backward compatible) */
+    private uncoordinatedWrite;
+    private registerInIndex;
+    private notifySubscribers;
+    /**
+     * Read the latest N entries from a channel (from local cache).
+     * For full history recovery from 0G, use `recoverChannel()`.
+     */
+    read(channel: string, limit?: number): MemoryEntry[];
+    /** Read a specific entry from 0G by its root hash */
+    readFromStorage(rootHash: string): Promise<{
+        data: string;
+        prevRootHash: string | null;
+    }>;
+    /**
+     * Search the memory index. Agents use this to discover root hashes
+     * without knowing them in advance.
+     */
+    search(query: {
+        label?: string;
+        tags?: string[];
+        channel?: string;
+        authorId?: string;
+        contentType?: IndexEntry["contentType"];
+        limit?: number;
+    }): IndexEntry[];
+    /** Look up what a specific root hash contains */
+    lookupRootHash(rootHash: string): IndexEntry | undefined;
+    /**
+     * Persist the full channel state as a snapshot on 0G.
+     */
+    snapshot(channel: string): Promise<string>;
+    /**
+     * Recover a channel by walking the linked list from a known head root hash.
+     */
+    recoverChannel(channel: string, headRootHash: string, maxDepth?: number): Promise<MemoryEntry[]>;
+    /**
+     * Ingest an entry from another agent (received via WebSocket broadcast).
+     * Keeps the local cache in sync without re-downloading from 0G.
+     */
+    ingestRemoteEntry(entry: MemoryEntry): void;
+    /** List all known channels */
+    listChannels(): ChannelManifest[];
+    /** Get a channel's manifest */
+    getChannel(name: string): ChannelManifest | undefined;
+}