@granular-software/sdk 0.4.58 → 0.4.60

package/README.md

@@ -751,26 +751,60 @@ Session history is always bounded (100 rows by default, 500 maximum). Increment
 `granular.listSessions()` also accepts `environmentId`, `sandboxId`, and
 `subjectId`; at least one ownership filter is required.
 
+### Canonical User And Assistant Ingress
+
+The live session API has no mixed-role message append. Browser and server
+callers append user input with an implicit user role:
+
+```ts
+await session.appendUserMessage({
+  id: "user_turn_42",
+  operationId: "send:user_turn_42",
+  content: "Compare the open requests.",
+  show: { fileIds: ["file_123"] },
+});
+```
+
+Only trusted API-key `EnvironmentSession` handles can publish a terminal
+assistant text occurrence:
+
+```ts
+await session.publishAssistantReply({
+  id: "assistant_turn_42",
+  operationId: "reply:assistant_turn_42",
+  text: "The comparison is ready.",
+});
+```
+
+Delegated browsers cannot call `publishAssistantReply()`. Generated jobs should
+author messages and components with the trusted Harness feed helpers.
+
 ### Live Session State And Durable Collections
 
 `session.document` and `session.getHeap()` are local, fast views of the live runtime state synced over the WebSocket.
 
-Older conversation history, timeline events, completed jobs, and saved heap artifacts are exposed through named durable collections:
+The canonical customer-visible history is the server-sequenced feed. The
+transcript is a message-oriented projection of that same feed. Timeline events
+and jobs are diagnostic collections; they are not presentation chronology.
+Saved heap artifacts remain available through their named collections:
 
 ```ts
 const session = await env.sessions.create();
 
 const liveHeap = session.getHeap();
-const messages = await session.messages.list({ limit: 100 });
+const feed = await session.feed.list({ afterSequence: 0, limit: 100 });
+const transcript = await session.transcript.list({ limit: 100 });
 const timeline = await session.timeline.list({ limit: 100 });
 const jobs = await session.jobs.list({ status: "all", limit: 100 });
 const job = await session.jobs.get("job_123");
 const entry = await session.heap.entries.get("customer_123");
 const savedList = await session.heap.lists.get("recent_customers");
-const transcript = await session.transcript.list({ limit: 100 });
 ```
 
-Use the live state for current working context, and the collection APIs when you need durable history or artifacts that may have been moved out of the live document.
+Use the live state for current resource lifecycle data, `feed.list()` for exact
+durable presentation order, and `transcript.list()` when only message-like
+history is needed. Page the feed by server sequence; never reconstruct display
+order from timeline events, jobs, or timestamps.
 
 ### `session.getDomainDocumentation()`
 

package/dist/agent-evals.d.mts

@@ -1,5 +1,5 @@
-import { a as EnvironmentSession, G as Granular } from './client-DFaCRSto.mjs';
-import { G as GranularSpendContext, h as OpenAITokenSpend, P as Prompt, bW as RecordObjectOptions, cL as ManifestContent, c as SessionHeapSnapshot, T as ToolWithHandler, K as ConnectOptions, ag as CreateEnvironmentData, y as GranularOptions } from './spend-czRX7l0X.mjs';
+import { a as EnvironmentSession, G as Granular } from './client-DSkGcmmX.mjs';
+import { at as GranularSpendContext, ao as OpenAITokenSpend, P as Prompt, cX as RecordObjectOptions, dN as ManifestContent, d as SessionHeapSnapshot, T as ToolWithHandler, aP as ConnectOptions, bd as CreateEnvironmentData, aI as GranularOptions } from './spend-CNe-Ff6U.mjs';
 import { GranularAgentToolInfo, GeneratedJobCodeIssue, BuildGranularAgentSystemPromptInput, HarnessRenderedPrompt, HarnessRenderedContinuation, HarnessControllerBudgets } from './agent-harness.mjs';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
@@ -369,7 +369,6 @@ interface AgentEvalPendingTurn {
     turnDir: string;
     boundaryTimestamp: number;
     finalCode: string;
-    finalReply: string;
     stdout: string[];
     stderr: string[];
     prompts: Prompt[];

package/dist/agent-evals.d.ts

@@ -1,5 +1,5 @@
-import { a as EnvironmentSession, G as Granular } from './client-UdGt44dF.js';
-import { G as GranularSpendContext, h as OpenAITokenSpend, P as Prompt, bW as RecordObjectOptions, cL as ManifestContent, c as SessionHeapSnapshot, T as ToolWithHandler, K as ConnectOptions, ag as CreateEnvironmentData, y as GranularOptions } from './spend-czRX7l0X.js';
+import { a as EnvironmentSession, G as Granular } from './client-BzgQvNyG.js';
+import { at as GranularSpendContext, ao as OpenAITokenSpend, P as Prompt, cX as RecordObjectOptions, dN as ManifestContent, d as SessionHeapSnapshot, T as ToolWithHandler, aP as ConnectOptions, bd as CreateEnvironmentData, aI as GranularOptions } from './spend-CNe-Ff6U.js';
 import { GranularAgentToolInfo, GeneratedJobCodeIssue, BuildGranularAgentSystemPromptInput, HarnessRenderedPrompt, HarnessRenderedContinuation, HarnessControllerBudgets } from './agent-harness.js';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
@@ -369,7 +369,6 @@ interface AgentEvalPendingTurn {
     turnDir: string;
     boundaryTimestamp: number;
     finalCode: string;
-    finalReply: string;
     stdout: string[];
     stderr: string[];
     prompts: Prompt[];