@covia/covia-sdk 1.24.0 → 1.24.2

package/README.md

@@ -408,6 +408,10 @@ await mina.delete();
 const clone = await mina.fork("Mina-v2", { includeTimeline: true });
 ```
 
+Create and fork require unused names. Use update to preserve an existing agent
+and its history. Deletion normally returns `status: "TERMINATED"`; physical
+removal (`remove: true`) returns `removed: true` without a status.
+
 #### Agent Instance
 
 | Method | Returns | Description |

package/dist/index.d.mts

@@ -46,7 +46,6 @@ declare class Agent {
     fork(agentId: string, options?: {
         config?: Record<string, unknown>;
         includeTimeline?: boolean;
-        overwrite?: boolean;
     }): Promise<Agent>;
     context(task?: unknown): Promise<string>;
     delete(remove?: boolean): Promise<AgentDeleteResult>;
@@ -1722,19 +1721,16 @@ declare enum AgentStatus {
     SUSPENDED = "SUSPENDED",
     TERMINATED = "TERMINATED"
 }
+/** Creates a new name only. Use update to preserve an existing agent and its history. */
 interface AgentCreateInput {
     agentId: string;
     config?: Record<string, any>;
     state?: Record<string, any>;
-    overwrite?: boolean;
 }
 interface AgentCreateResult {
     agentId: string;
     status: string;
-    created: boolean;
-    /** True when an existing SLEEPING/SUSPENDED record was updated in place
-     *  (mutually exclusive with created). Absent on venues before 0.4. */
-    updated?: boolean;
+    address?: string;
     /** Non-fatal advisories (venue 0.5+): present only when the config looks
      *  misconfigured but create still succeeded — e.g. an Ollama model whose
      *  tool-calling can't be confirmed, or declared tools that don't resolve
@@ -1807,7 +1803,9 @@ interface AgentDeleteInput {
 }
 interface AgentDeleteResult {
     agentId: string;
-    status: string;
+    address?: string;
+    /** Present on logical termination; absent on physical removal. */
+    status?: string;
     removed?: boolean;
 }
 interface AgentSuspendResult {
@@ -1886,9 +1884,9 @@ interface AgentSessionMessage {
     tokens?: number;
 }
 /**
- * An archived run of turns that compaction replaced with a summary
+ * A legacy archived run of turns that compaction replaced with a summary
  * (AGENT_CONTEXT.md §1.1 `CompactedSegment`). `items` is the exact recursively
- * archived vector, so no history is lost — {@link AgentSession.conversation}
+ * archived vector (new frame histories use backward historyRange references), so no history is lost — {@link AgentSession.conversation}
  * expands it back into the transcript.
  */
 interface AgentCompactedSegment {
@@ -1936,17 +1934,17 @@ interface AgentSessionPage {
     offset: number;
     limit: number;
 }
+/** Forks into an unused name; replacement requires explicit deletion first. */
 interface AgentForkInput {
     sourceId: string;
     agentId: string;
     config?: Record<string, any>;
     includeTimeline?: boolean;
-    overwrite?: boolean;
 }
 interface AgentForkResult {
     agentId: string;
+    address?: string;
     status: string;
-    created: boolean;
     forkedFrom: string;
 }
 interface AgentContextInput {

package/dist/index.d.ts

@@ -46,7 +46,6 @@ declare class Agent {
     fork(agentId: string, options?: {
         config?: Record<string, unknown>;
         includeTimeline?: boolean;
-        overwrite?: boolean;
     }): Promise<Agent>;
     context(task?: unknown): Promise<string>;
     delete(remove?: boolean): Promise<AgentDeleteResult>;
@@ -1722,19 +1721,16 @@ declare enum AgentStatus {
     SUSPENDED = "SUSPENDED",
     TERMINATED = "TERMINATED"
 }
+/** Creates a new name only. Use update to preserve an existing agent and its history. */
 interface AgentCreateInput {
     agentId: string;
     config?: Record<string, any>;
     state?: Record<string, any>;
-    overwrite?: boolean;
 }
 interface AgentCreateResult {
     agentId: string;
     status: string;
-    created: boolean;
-    /** True when an existing SLEEPING/SUSPENDED record was updated in place
-     *  (mutually exclusive with created). Absent on venues before 0.4. */
-    updated?: boolean;
+    address?: string;
     /** Non-fatal advisories (venue 0.5+): present only when the config looks
      *  misconfigured but create still succeeded — e.g. an Ollama model whose
      *  tool-calling can't be confirmed, or declared tools that don't resolve
@@ -1807,7 +1803,9 @@ interface AgentDeleteInput {
 }
 interface AgentDeleteResult {
     agentId: string;
-    status: string;
+    address?: string;
+    /** Present on logical termination; absent on physical removal. */
+    status?: string;
     removed?: boolean;
 }
 interface AgentSuspendResult {
@@ -1886,9 +1884,9 @@ interface AgentSessionMessage {
     tokens?: number;
 }
 /**
- * An archived run of turns that compaction replaced with a summary
+ * A legacy archived run of turns that compaction replaced with a summary
  * (AGENT_CONTEXT.md §1.1 `CompactedSegment`). `items` is the exact recursively
- * archived vector, so no history is lost — {@link AgentSession.conversation}
+ * archived vector (new frame histories use backward historyRange references), so no history is lost — {@link AgentSession.conversation}
  * expands it back into the transcript.
  */
 interface AgentCompactedSegment {
@@ -1936,17 +1934,17 @@ interface AgentSessionPage {
     offset: number;
     limit: number;
 }
+/** Forks into an unused name; replacement requires explicit deletion first. */
 interface AgentForkInput {
     sourceId: string;
     agentId: string;
     config?: Record<string, any>;
     includeTimeline?: boolean;
-    overwrite?: boolean;
 }
 interface AgentForkResult {
     agentId: string;
+    address?: string;
     status: string;
-    created: boolean;
     forkedFrom: string;
 }
 interface AgentContextInput {

package/dist/index.js

@@ -1931,11 +1931,42 @@ function collectTurns(entries, out, depth = 0) {
     }
   }
 }
+function collectHistory(frame, out) {
+  const history = frame.history;
+  const start = frame.contextStart;
+  if (frame.historyVersion !== void 0 && frame.historyVersion !== 1 || "conversation" in frame || !Array.isArray(history) || !Number.isSafeInteger(start) || start < 0 || start > history.length) {
+    throw new Error("Invalid or unsupported agent frame history");
+  }
+  const pending = [[start, history.length]];
+  const visited = /* @__PURE__ */ new Set();
+  while (pending.length) {
+    const [from, end] = pending.pop();
+    for (let i = from; i < end; i++) {
+      if (visited.has(i)) continue;
+      visited.add(i);
+      const entry = record(history[i]);
+      if (!entry) continue;
+      if ("historyRange" in entry) {
+        const range = entry.historyRange;
+        if (typeof entry.summary !== "string" || "items" in entry || !Number.isSafeInteger(entry.turns) || entry.turns < 0 || !Array.isArray(range) || range.length !== 2 || !range.every(Number.isSafeInteger) || range[0] < 0 || range[1] < range[0] || range[1] > i) {
+          throw new Error("Invalid agent summary historyRange");
+        }
+        pending.push([i + 1, end], [range[0], range[1]]);
+        break;
+      }
+      collectTurns([entry], out);
+    }
+  }
+}
 function sessionConversation(frames) {
   const turns = [];
   for (const frame of frames) {
-    const entries = record(frame)?.conversation;
-    if (Array.isArray(entries)) collectTurns(entries, turns);
+    const value = record(frame);
+    if (!value) continue;
+    if ("history" in value) collectHistory(value, turns);
+    else if ("historyVersion" in value || "contextStart" in value) {
+      throw new Error("Invalid or unsupported agent frame history");
+    } else if (Array.isArray(value.conversation)) collectTurns(value.conversation, turns);
   }
   return turns;
 }

package/dist/index.mjs

@@ -1929,11 +1929,42 @@ function collectTurns(entries, out, depth = 0) {
     }
   }
 }
+function collectHistory(frame, out) {
+  const history = frame.history;
+  const start = frame.contextStart;
+  if (frame.historyVersion !== void 0 && frame.historyVersion !== 1 || "conversation" in frame || !Array.isArray(history) || !Number.isSafeInteger(start) || start < 0 || start > history.length) {
+    throw new Error("Invalid or unsupported agent frame history");
+  }
+  const pending = [[start, history.length]];
+  const visited = /* @__PURE__ */ new Set();
+  while (pending.length) {
+    const [from, end] = pending.pop();
+    for (let i = from; i < end; i++) {
+      if (visited.has(i)) continue;
+      visited.add(i);
+      const entry = record(history[i]);
+      if (!entry) continue;
+      if ("historyRange" in entry) {
+        const range = entry.historyRange;
+        if (typeof entry.summary !== "string" || "items" in entry || !Number.isSafeInteger(entry.turns) || entry.turns < 0 || !Array.isArray(range) || range.length !== 2 || !range.every(Number.isSafeInteger) || range[0] < 0 || range[1] < range[0] || range[1] > i) {
+          throw new Error("Invalid agent summary historyRange");
+        }
+        pending.push([i + 1, end], [range[0], range[1]]);
+        break;
+      }
+      collectTurns([entry], out);
+    }
+  }
+}
 function sessionConversation(frames) {
   const turns = [];
   for (const frame of frames) {
-    const entries = record(frame)?.conversation;
-    if (Array.isArray(entries)) collectTurns(entries, turns);
+    const value = record(frame);
+    if (!value) continue;
+    if ("history" in value) collectHistory(value, turns);
+    else if ("historyVersion" in value || "contextStart" in value) {
+      throw new Error("Invalid or unsupported agent frame history");
+    } else if (Array.isArray(value.conversation)) collectTurns(value.conversation, turns);
   }
   return turns;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@covia/covia-sdk",
-  "version": "1.24.0",
+  "version": "1.24.2",
   "description": "Typescript library for covia-ai",
   "packageManager": "pnpm@11.9.0",
   "main": "./dist/index.js",