@forbocai/core 0.5.4 → 0.5.7

package/dist/ans104-GLQVFKBA.mjs

@@ -0,0 +1,224 @@
+import "./chunk-7P6ASYW6.mjs";
+
+// src/ans104.ts
+import base64url from "base64url";
+import { Buffer } from "buffer";
+import { constants, createHash, createSign } from "crypto";
+import { jwkTopem } from "arweave/node/lib/crypto/pem";
+var SIGNATURE_TYPE_ARWEAVE = 1;
+var SIGNATURE_LENGTH = 512;
+var OWNER_LENGTH = 512;
+var MAX_TAG_BYTES = 4096;
+var stringToBuffer = (value) => Buffer.from(value);
+var concatBuffers = (buffers) => Buffer.concat(buffers);
+var longToNByteArray = (bytes, long) => {
+  const byteArray = new Uint8Array(bytes);
+  if (long < 0) throw new Error("Array is unsigned, cannot represent -ve numbers");
+  if (long > 2 ** (bytes * 8) - 1) throw new Error(`Number ${long} is too large for an array of ${bytes} bytes`);
+  for (let index = 0; index < byteArray.length; index++) {
+    const byte = long & 255;
+    byteArray[index] = byte;
+    long = (long - byte) / 256;
+  }
+  return byteArray;
+};
+var longTo8ByteArray = (long) => longToNByteArray(8, long);
+var shortTo2ByteArray = (short) => longToNByteArray(2, short);
+var AVSCTap = class {
+  constructor(buf = Buffer.alloc(MAX_TAG_BYTES), pos = 0) {
+    this.buf = buf;
+    this.pos = pos;
+  }
+  writeTags(tags) {
+    if (!Array.isArray(tags)) {
+      throw new Error("input must be array");
+    }
+    const n = tags.length;
+    if (n) {
+      this.writeLong(n);
+      for (let i = 0; i < n; i++) {
+        const tag = tags[i];
+        if (typeof tag?.name !== "string" || typeof tag?.value !== "string") {
+          throw new Error(`Invalid tag format for ${tag}, expected {name:string, value: string}`);
+        }
+        this.writeString(tag.name);
+        this.writeString(tag.value);
+      }
+    }
+    this.writeLong(0);
+  }
+  toBuffer() {
+    const buffer = Buffer.alloc(this.pos);
+    if (this.pos > this.buf.length) throw new Error(`Too many tag bytes (${this.pos} > ${this.buf.length})`);
+    this.buf.copy(buffer, 0, 0, this.pos);
+    return buffer;
+  }
+  writeLong(n) {
+    const buf = this.buf;
+    let f, m;
+    if (n >= -1073741824 && n < 1073741824) {
+      m = n >= 0 ? n << 1 : ~n << 1 | 1;
+      do {
+        buf[this.pos] = m & 127;
+        m >>= 7;
+      } while (m && (buf[this.pos++] |= 128));
+    } else {
+      f = n >= 0 ? n * 2 : -n * 2 - 1;
+      do {
+        buf[this.pos] = f & 127;
+        f /= 128;
+      } while (f >= 1 && (buf[this.pos++] |= 128));
+    }
+    this.pos++;
+    this.buf = buf;
+  }
+  writeString(s) {
+    const len = Buffer.byteLength(s);
+    const buf = this.buf;
+    this.writeLong(len);
+    let pos = this.pos;
+    this.pos += len;
+    if (this.pos > buf.length) {
+      return;
+    }
+    if (len > 64) {
+      this.buf.write(s, this.pos - len, len, "utf8");
+    } else {
+      let i, l, c1, c2;
+      for (i = 0, l = len; i < l; i++) {
+        c1 = s.charCodeAt(i);
+        if (c1 < 128) {
+          buf[pos++] = c1;
+        } else if (c1 < 2048) {
+          buf[pos++] = c1 >> 6 | 192;
+          buf[pos++] = c1 & 63 | 128;
+        } else if ((c1 & 64512) === 55296 && ((c2 = s.charCodeAt(i + 1)) & 64512) === 56320) {
+          c1 = 65536 + ((c1 & 1023) << 10) + (c2 & 1023);
+          i++;
+          buf[pos++] = c1 >> 18 | 240;
+          buf[pos++] = c1 >> 12 & 63 | 128;
+          buf[pos++] = c1 >> 6 & 63 | 128;
+          buf[pos++] = c1 & 63 | 128;
+        } else {
+          buf[pos++] = c1 >> 12 | 224;
+          buf[pos++] = c1 >> 6 & 63 | 128;
+          buf[pos++] = c1 & 63 | 128;
+        }
+      }
+    }
+    this.buf = buf;
+  }
+};
+var serializeTags = (tags) => {
+  if (tags?.length === 0) {
+    return Buffer.allocUnsafe(0);
+  }
+  const tap = new AVSCTap();
+  tap.writeTags(tags);
+  return tap.toBuffer();
+};
+var hash = (data, algorithm) => {
+  const algo = algorithm === "SHA-256" ? "sha256" : "sha384";
+  return createHash(algo).update(data).digest();
+};
+var deepHash = async (data) => {
+  if (Array.isArray(data)) {
+    const tag2 = concatBuffers([stringToBuffer("list"), stringToBuffer(data.length.toString())]);
+    return deepHashChunks(data, hash(tag2, "SHA-384"));
+  }
+  const _data = data;
+  const tag = concatBuffers([stringToBuffer("blob"), stringToBuffer(_data.byteLength.toString())]);
+  const taggedHash = concatBuffers([hash(tag, "SHA-384"), hash(_data, "SHA-384")]);
+  return hash(taggedHash, "SHA-384");
+};
+var deepHashChunks = async (chunks, acc) => {
+  if (chunks.length < 1) {
+    return acc;
+  }
+  const hashPair = concatBuffers([acc, await deepHash(chunks[0])]);
+  const newAcc = hash(hashPair, "SHA-384");
+  return deepHashChunks(chunks.slice(1), newAcc);
+};
+var getSignatureData = async (signatureType, rawOwner, rawTarget, rawAnchor, rawTags, rawData) => {
+  return deepHash([
+    stringToBuffer("dataitem"),
+    stringToBuffer("1"),
+    stringToBuffer(signatureType.toString()),
+    rawOwner,
+    rawTarget,
+    rawAnchor,
+    rawTags,
+    rawData
+  ]);
+};
+var signData = async (pemKey, message) => {
+  return createSign("sha256").update(message).sign({
+    key: pemKey,
+    padding: constants.RSA_PKCS1_PSS_PADDING
+  });
+};
+var getOwner = (jwk) => {
+  return base64url.toBuffer(jwk.n);
+};
+var getPem = (jwk) => {
+  const pem = jwkTopem(jwk);
+  return typeof pem === "string" ? pem : pem.toString();
+};
+var createArweaveDataItem = async (data, jwk, opts) => {
+  const rawOwner = getOwner(jwk);
+  if (rawOwner.byteLength !== OWNER_LENGTH) {
+    throw new Error(`Owner must be ${OWNER_LENGTH} bytes, but was ${rawOwner.byteLength}`);
+  }
+  const rawTarget = opts?.target ? base64url.toBuffer(opts.target) : Buffer.alloc(0);
+  const rawAnchor = opts?.anchor ? Buffer.from(opts.anchor) : Buffer.alloc(0);
+  const rawTags = (opts?.tags?.length ?? 0) > 0 ? serializeTags(opts?.tags) : Buffer.alloc(0);
+  const rawData = typeof data === "string" ? Buffer.from(data) : Buffer.from(data);
+  const targetLength = 1 + (rawTarget?.byteLength ?? 0);
+  const anchorLength = 1 + (rawAnchor?.byteLength ?? 0);
+  const tagsLength = 16 + (rawTags ? rawTags.byteLength : 0);
+  const dataLength = rawData.byteLength;
+  const length = 2 + SIGNATURE_LENGTH + OWNER_LENGTH + targetLength + anchorLength + tagsLength + dataLength;
+  const bytes = Buffer.alloc(length);
+  bytes.set(shortTo2ByteArray(SIGNATURE_TYPE_ARWEAVE), 0);
+  bytes.set(new Uint8Array(SIGNATURE_LENGTH).fill(0), 2);
+  bytes.set(rawOwner, 2 + SIGNATURE_LENGTH);
+  const position = 2 + SIGNATURE_LENGTH + OWNER_LENGTH;
+  bytes[position] = rawTarget.length > 0 ? 1 : 0;
+  if (rawTarget.length > 0) {
+    if (rawTarget.byteLength !== 32) throw new Error("Target must be 32 bytes");
+    bytes.set(rawTarget, position + 1);
+  }
+  const anchorStart = position + targetLength;
+  let tagsStart = anchorStart + 1;
+  bytes[anchorStart] = rawAnchor.length > 0 ? 1 : 0;
+  if (rawAnchor.length > 0) {
+    tagsStart += rawAnchor.byteLength;
+    if (rawAnchor.byteLength !== 32) throw new Error("Anchor must be 32 bytes");
+    bytes.set(rawAnchor, anchorStart + 1);
+  }
+  bytes.set(longTo8ByteArray(opts?.tags?.length ?? 0), tagsStart);
+  bytes.set(longTo8ByteArray(rawTags?.byteLength ?? 0), tagsStart + 8);
+  if (rawTags.length > 0) {
+    bytes.set(rawTags, tagsStart + 16);
+  }
+  const dataStart = tagsStart + tagsLength;
+  bytes.set(rawData, dataStart);
+  const signatureData = await getSignatureData(
+    SIGNATURE_TYPE_ARWEAVE,
+    rawOwner,
+    rawTarget,
+    rawAnchor,
+    rawTags,
+    rawData
+  );
+  const signature = await signData(getPem(jwk), signatureData);
+  bytes.set(signature, 2);
+  const id = hash(signature, "SHA-256");
+  return {
+    id: base64url.encode(id),
+    raw: bytes
+  };
+};
+export {
+  createArweaveDataItem
+};

package/dist/chunk-7P6ASYW6.mjs

@@ -0,0 +1,9 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};

package/dist/index.d.mts

@@ -30,55 +30,40 @@ interface CompletionOptions {
     stop?: string[];
     jsonSchema?: object;
 }
-type Mood = string;
 interface AgentState {
     [key: string]: unknown;
 }
+/** Interface for Memory module operations used by the Agent. */
+interface IMemory {
+    store(text: string, type?: string, importance?: number): Promise<MemoryItem>;
+    recall(query: string, limit?: number, threshold?: number): Promise<MemoryItem[]>;
+    list(limit?: number, offset?: number): Promise<MemoryItem[]>;
+    clear(): Promise<void>;
+    export(): Promise<MemoryItem[]>;
+    import(memories: MemoryItem[]): Promise<void>;
+}
 interface AgentConfig {
     id: string;
     cortex: ICortex;
-    memory: any;
+    memory: IMemory | null;
     persona: string;
     initialState?: Partial<AgentState>;
-    memoryConfig?: MemoryConfig;
     apiUrl?: string;
+    apiKey?: string;
 }
 interface AgentResponse {
     dialogue: string;
     action?: AgentAction;
     thought?: string;
 }
-type MemoryType = string;
-interface MemoryConfig {
-    /** Decay strategy: 'none' | 'temporal' */
-    decay?: 'none' | 'temporal';
-    /** Max memories to keep in active context during retrieval */
-    maxContextWindow?: number;
-}
 interface MemoryItem {
     id: string;
     text: string;
     embedding?: number[];
     timestamp: number;
-    type: MemoryType;
+    type: string;
     importance: number;
 }
-interface Observation {
-    type: 'event' | 'state' | 'request';
-    timestamp: number;
-    agentId?: string;
-    gameId?: string;
-    content: string;
-    data?: Record<string, unknown>;
-    context?: Record<string, unknown>;
-}
-interface Directive {
-    type: 'system-prompt' | 'action-constraints' | 'behavior-rules' | 'thought';
-    content: string;
-    constraints?: Record<string, unknown>;
-    priority?: 'high' | 'normal' | 'low';
-    expiresAt?: number;
-}
 interface AgentAction {
     type: string;
     target?: string;
@@ -116,6 +101,20 @@ interface RecalledMemory {
     importance: number;
     similarity?: number;
 }
+/** Speak Request (Simple Dialogue) */
+interface SpeakRequest {
+    speakMessage: string;
+    speakContext?: Record<string, unknown>;
+    speakAgentState: Record<string, unknown>;
+}
+/** Speak Response (Simple Dialogue) */
+interface SpeakResponse {
+    speakReply: string;
+    speakHistory: Array<{
+        role: string;
+        content: string;
+    }>;
+}
 /** Step 5: API → SDK. API returns full SLM prompt + constraints. */
 interface ContextResponse {
     prompt: string;
@@ -187,6 +186,17 @@ interface IAgent {
      * @returns A promise that resolves to the agent's response.
      */
     process(input: string, context?: Record<string, unknown>): Promise<AgentResponse>;
+    /**
+     * Generates a conversational response (bypassing the multi-round ruleset evaluation).
+     * @param message - The input message.
+     * @param context - Optional context overrides.
+     * @returns A promise resolving to the agent's textual reply.
+     */
+    speak(message: string, context?: Record<string, unknown>): Promise<string>;
+    /**
+     * Alias for `speak()`.
+     */
+    reply(message: string, context?: Record<string, unknown>): Promise<string>;
     /**
      * Retrieves the current state of the agent.
      * @returns The current AgentState.
@@ -217,14 +227,6 @@ declare const createInitialState: (partial?: Partial<AgentState>) => AgentState;
  * @returns A new AgentState object with the updates applied.
  */
 declare const updateAgentState: (currentState: AgentState, updates: Partial<AgentState>) => AgentState;
-/**
- * Pure function to process input and generate response
- * @param currentState - The current state of the agent.
- * @param input - The input string to process.
- * @param context - Optional context data.
- * @returns The agent's response including dialogue and action.
- */
-declare const processAgentInput: (currentState: AgentState, input: string, context?: Record<string, unknown>) => AgentResponse;
 /**
  * Pure function to export agent to Soul
  * @param agentId - The ID of the agent.
@@ -249,7 +251,7 @@ declare const createAgent: (config: AgentConfig) => IAgent;
  * @param memory - Optional memory instance.
  * @returns An instantiated IAgent.
  */
-declare const fromSoul: (soul: Soul, cortex: ICortex, memory?: any) => Promise<IAgent>;
+declare const fromSoul: (soul: Soul, cortex: ICortex, memory?: IMemory | null) => Promise<IAgent>;
 
 /**
  * Bridge configuration
@@ -309,22 +311,22 @@ declare const validateAction: (action: AgentAction, rules: readonly ValidationRu
  * Soul export configuration
  */
 interface SoulExportConfig {
-    /** API URL for remote upload/pinning */
-    apiUrl?: string;
     /** Include memories in export */
     includeMemories?: boolean;
-    /** Private key for signing/uploading directly to Arweave via Irys */
-    privateKey?: string;
-    /** RPC URL for Irys (defaults to https://node1.irys.xyz) */
-    irysUrl?: string;
-    /** Token/Currency (default: 'solana') */
-    token?: string;
+    /** Arweave wallet JWK (object or JSON string) for direct uploads */
+    walletJwk?: Record<string, unknown> | string;
+    /** Deprecated: use walletJwk */
+    privateKey?: Record<string, unknown> | string;
+    /** Bundler URL for ANS-104 data item uploads */
+    bundlerUrl?: string;
+    /** Gateway URL for read access (default: https://arweave.net) */
+    gatewayUrl?: string;
 }
 /**
  * Soul export result
  */
 interface SoulExportResult {
-    /** Arweave Transaction ID (TXID) */
+    /** Arweave data item ID (TXID) */
     txId: string;
     /** Gateway URL to access the soul. */
     url: string;
@@ -335,9 +337,7 @@ interface SoulExportResult {
  * Soul import configuration
  */
 interface SoulImportConfig {
-    /** API URL for retrieval */
-    apiUrl?: string;
-    /** Gateway URL for Arweave (defaults to https://gateway.irys.xyz) */
+    /** Gateway URL for Arweave (defaults to https://arweave.net) */
     gatewayUrl?: string;
 }
 /**
@@ -369,13 +369,13 @@ declare const serializeSoul: (soul: Soul) => string;
  */
 declare const deserializeSoul: (json: string) => Soul;
 /**
- * Pure function to upload Soul to Arweave via Irys
+ * Pure function to upload Soul to Arweave using ANS-104 data items
  */
 declare const uploadToArweave: (soul: Soul, config: SoulExportConfig) => Promise<SoulExportResult>;
 /**
- * Export agent Soul to Arweave (Irys or API)
+ * Export agent Soul to Arweave (direct ANS-104 or API)
  */
-declare const exportSoul: (agentId: string, soul: Soul, config?: SoulExportConfig) => Promise<SoulExportResult>;
+declare const exportSoul: (_agentId: string, soul: Soul, config?: SoulExportConfig) => Promise<SoulExportResult>;
 /**
  * Import Soul from Arweave by TXID
  */
@@ -397,7 +397,7 @@ declare const getSoulList: (limit?: number, apiUrl?: string) => Promise<SoulList
 /**
  * Factory function to create Soul instance
  */
-declare const createSoulInstance: (id: string, name: string, persona: string, state: AgentState, memories?: MemoryItem[], initialApiUrl?: string) => ISoul;
+declare const createSoulInstance: (id: string, name: string, persona: string, state: AgentState, memories?: MemoryItem[]) => ISoul;
 /**
  * Pure function to validate a Soul object
  */
@@ -406,9 +406,6 @@ declare const validateSoul: (soul: Soul) => {
     errors: string[];
 };
 
-/**
- * Ghost test configuration
- */
 /**
  * Ghost test configuration
  */
@@ -424,9 +421,6 @@ interface GhostConfig {
     /** Custom test parameters */
     params?: Record<string, unknown>;
 }
-/**
- * Ghost session status
- */
 /**
  * Ghost session status
  */
@@ -444,9 +438,6 @@ interface GhostStatus {
     /** Number of errors encountered. */
     errors: number;
 }
-/**
- * Individual test result
- */
 /**
  * Individual test result
  */
@@ -462,9 +453,6 @@ interface GhostTestResult {
     /** URL or path to a screenshot if captured. */
     screenshot?: string;
 }
-/**
- * Complete session results
- */
 /**
  * Complete session results
  */
@@ -488,9 +476,6 @@ interface GhostResults {
     /** Additional metrics collected during the session. */
     metrics: Record<string, number>;
 }
-/**
- * Interface for Ghost operations
- */
 /**
  * Interface for Ghost operations
  */
@@ -595,7 +580,48 @@ declare const createGhost: (config: GhostConfig) => IGhost;
  * Creates a remote Cortex instance that proxies inference to the ForbocAI API.
  * This is environment-agnostic as it only uses the standard fetch API.
  */
-declare const createRemoteCortex: (apiUrl: string) => ICortex;
+declare const createRemoteCortex: (apiUrl: string, cortexId?: string, apiKey?: string) => ICortex;
+
+/**
+ * Consume an async token stream, calling `onChunk` for each token.
+ * Useful for rendering typewriter effects in UI.
+ */
+declare function streamToCallback(stream: AsyncGenerator<string, void, unknown>, onChunk: (chunk: string) => void): Promise<void>;
+/**
+ * Consume an async token stream and return the full accumulated string.
+ */
+declare function streamToString(stream: AsyncGenerator<string, void, unknown>): Promise<string>;
+/**
+ * Stream tokens from a cortex directly to a callback.
+ * Convenience wrapper combining cortex.completeStream + streamToCallback.
+ *
+ * @example
+ * // Typewriter effect in a React component:
+ * await streamFromCortex(cortex, prompt, (token) => {
+ *   setDisplayText(prev => prev + token);
+ * });
+ */
+declare function streamFromCortex(cortex: ICortex, prompt: string, onChunk: (chunk: string) => void, options?: {
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+}): Promise<string>;
+/**
+ * Stream tokens from a cortex with a delay between tokens (for typewriter pacing).
+ *
+ * @param delayMs - Milliseconds to wait between tokens (default: 30ms)
+ *
+ * @example
+ * await streamFromCortexWithDelay(cortex, prompt, (token) => {
+ *   setDisplayText(prev => prev + token);
+ * }, { delayMs: 25 });
+ */
+declare function streamFromCortexWithDelay(cortex: ICortex, prompt: string, onChunk: (chunk: string) => void, options?: {
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+    delayMs?: number;
+}): Promise<string>;
 
 interface RPGAgentState extends AgentState {
     inventory: string[];
@@ -646,6 +672,6 @@ declare namespace index {
   export { type index_RPGAgentState as RPGAgentState, index_RPG_MEMORY_TYPES as RPG_MEMORY_TYPES, index_RPG_MOODS as RPG_MOODS, index_attackRule as attackRule, index_createRPGState as createRPGState, index_interactRule as interactRule, index_movementRule as movementRule, index_puzzleRules as puzzleRules, index_resourceRule as resourceRule, index_rpgRules as rpgRules, index_socialRules as socialRules, index_spatialRules as spatialRules, index_speakRule as speakRule };
 }
 
-declare const SDK_VERSION = "0.5.4";
+declare const SDK_VERSION = "0.5.7";
 
-export { type AgentAction, type AgentConfig, type AgentResponse, type AgentState, type BridgeConfig, type CompletionOptions, type ContextRequest, type ContextResponse, type CortexConfig, type CortexStatus, type Directive, type DirectiveRequest, type DirectiveResponse, type GhostConfig, type GhostHistoryEntry, type GhostResults, type GhostStatus, type GhostTestResult, type IAgent, type IBridge, type ICortex, type IGhost, type ISoul, type MemoryConfig, type MemoryItem, type MemoryRecallInstruction, type MemoryStoreInstruction, type MemoryType, type Mood, type Observation, type PromptConstraints, type RecalledMemory, SDK_VERSION, type Soul, type SoulExportConfig, type SoulExportResult, type SoulImportConfig, type SoulListEntry, type ValidationContext, type ValidationResult, type ValidationRule, type VerdictRequest, type VerdictResponse, createAgent, createBridge, createGhost, createInitialState, createRemoteCortex, createSoul, createSoulInstance, deserializeSoul, exportSoul, exportToSoul, fromSoul, getGhostHistory, getGhostResults, getGhostStatus, getSoulList, importSoulFromArweave, index as presets, processAgentInput, serializeSoul, startGhostSession, stopGhostSession, updateAgentState, uploadToArweave, validateAction, validateSoul, waitForGhostCompletion };
+export { type AgentAction, type AgentConfig, type AgentResponse, type AgentState, type BridgeConfig, type CompletionOptions, type ContextRequest, type ContextResponse, type CortexConfig, type CortexStatus, type DirectiveRequest, type DirectiveResponse, type GhostConfig, type GhostHistoryEntry, type GhostResults, type GhostStatus, type GhostTestResult, type IAgent, type IBridge, type ICortex, type IGhost, type IMemory, type ISoul, type MemoryItem, type MemoryRecallInstruction, type MemoryStoreInstruction, type PromptConstraints, type RecalledMemory, SDK_VERSION, type Soul, type SoulExportConfig, type SoulExportResult, type SoulImportConfig, type SoulListEntry, type SpeakRequest, type SpeakResponse, type ValidationContext, type ValidationResult, type ValidationRule, type VerdictRequest, type VerdictResponse, createAgent, createBridge, createGhost, createInitialState, createRemoteCortex, createSoul, createSoulInstance, deserializeSoul, exportSoul, exportToSoul, fromSoul, getGhostHistory, getGhostResults, getGhostStatus, getSoulList, importSoulFromArweave, index as presets, serializeSoul, startGhostSession, stopGhostSession, streamFromCortex, streamFromCortexWithDelay, streamToCallback, streamToString, updateAgentState, uploadToArweave, validateAction, validateSoul, waitForGhostCompletion };