Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/quiet-assistant-continuation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@sapiom/harness": patch
---

Prepare bounded Assistant continuation briefs and retryable acceptance of frozen child context.
21 changes: 21 additions & 0 deletions packages/harness/docs/assistant-continuation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Assistant continuation

Continue reconstructs context from a retained public Assistant record. The brief
names the source Studio session, native conversation, workspace and exact record
revision. It retains at most twelve recent turns within the existing 6,000-token
estimate, explicitly marks omissions and incomplete turns, and directs the
Assistant to wait for the next user message. It never implies restored native
memory or successful completion of interrupted work.

The lifecycle operation must freeze the child's context candidate and its own
acceptance ID durably before calling `AssistantContextDelivery.acceptFrozen`.
That method validates and detaches all input before authority checks, then uses
the existing accepted-source store. An identical retry preserves the acceptance;
conflicting input fails. The child must have its own Studio identity, native
conversation and authority scope. A parent's accepted reference is not reusable.

Frozen operation input is not a replacement accepted-source store. Composition
and recovery continue to read the exact retained acceptance through the shared
delivery coordinator. Missing committed material remains an execution error.
Native creation, synthetic no-reply seeding, operation receipts, and the public
Continue action are separate lifecycle consumers of these primitives.
102 changes: 102 additions & 0 deletions packages/harness/src/core/assistant-continuation-brief.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
import { createHash } from "node:crypto";
import { expect, it } from "vitest";
import type { AssistantRecord } from "../shared/assistant-record.js";
import { buildAssistantContinuationBrief } from "./assistant-continuation-brief.js";
import { projectAssistantRecord } from "./assistant-record.js";

const binding = {
harnessSessionId: "studio-source",
conversationId: "ses_source",
contextAuthorityScope: "a".repeat(64),
cwd: "/workspace/project",
};
function fixture(count = 1): AssistantRecord {
return projectAssistantRecord(
Array.from({ length: count }, (_, index) => ({
info: {
id: `msg_user_${index}`,
role: "user",
sessionID: binding.conversationId,
time: { created: index + 1 },
},
parts: [
{
id: `prt_text_${index}`,
messageID: `msg_user_${index}`,
sessionID: binding.conversationId,
type: "text",
text: `Task ${index}: preserve current work.`,
},
],
})),
binding,
7,
"2026-09-14T12:00:00.000Z",
);
}
it("freezes one exact public revision with reconstruction and no-replay provenance", () => {
const record = fixture();
const frozen = buildAssistantContinuationBrief(record);
expect(frozen).toMatchObject({
version: 1,
binding,
recordRevision: 7,
retainedTurns: 1,
omittedTurns: 0,
});
expect(frozen.text).toContain("not restored native memory or a new task");
expect(frozen.text).toContain("Do not replay completed tools");
expect(frozen.text).toContain("incomplete; do not assume success");
expect(frozen.text).toContain("accepted-context-unavailable");
expect(frozen.sha256).toBe(
createHash("sha256").update(frozen.text).digest("hex"),
);
const original = frozen.text;
record.turns[0]!.messages[0]!.parts = [];
record.binding.cwd = "/other";
expect(frozen.text).toBe(original);
expect(frozen.binding.cwd).toBe("/workspace/project");
});
it("keeps at most twelve recent turns and reports all omissions", () => {
const frozen = buildAssistantContinuationBrief(fixture(20));
expect(frozen.retainedTurns).toBe(12);
expect(frozen.omittedTurns).toBe(8);
expect(frozen.text).not.toContain("Task 0:");
expect(frozen.text).toContain("Task 19:");
expect(frozen.estimatedTokens).toBeLessThanOrEqual(6000);
});
it("bounds an oversized final turn without dropping the honesty block", () => {
const record = fixture();
record.turns[0]!.messages.push(
...Array.from({ length: 30 }, (_, index) => ({
id: `msg_reply_${index}`,
role: "assistant" as const,
parentId: "msg_user_0",
createdAt: index + 2,
completedAt: null,
parts: [
{
id: `prt_long_${index}`,
type: "text" as const,
text: "data ".repeat(240),
truncated: false,
},
],
})),
);
record.messageCount = 31;
const frozen = buildAssistantContinuationBrief(record);
expect(frozen.estimatedTokens).toBeLessThanOrEqual(6000);
expect(frozen.text).toContain("excerpt truncated");
expect(frozen.text).toContain("Record revision 7");
});
it("fails without usable public history or with corrupt binding metadata", () => {
const empty = fixture(0);
expect(() => buildAssistantContinuationBrief(empty)).toThrow("unavailable");
expect(() =>
buildAssistantContinuationBrief({
...fixture(),
binding: { ...binding, conversationId: "studio-source" },
}),
).toThrow();
});
110 changes: 110 additions & 0 deletions packages/harness/src/core/assistant-continuation-brief.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
import { createHash } from "node:crypto";
import type {
AssistantRecord,
AssistantRecordBinding,
} from "../shared/assistant-record.js";
import { validateAssistantRecord } from "./assistant-record.js";
import {
estimateBriefTokens,
RESUME_BRIEF_DEFAULT_MAX_TOKENS,
RESUME_BRIEF_DEFAULT_MAX_TURNS,
} from "./resume-brief.js";

export interface AssistantContinuationBrief {
version: 1;
binding: AssistantRecordBinding;
recordRevision: number;
capturedAt: string;
text: string;
sha256: string;
estimatedTokens: number;
retainedTurns: number;
omittedTurns: number;
}
const clamp = (value: string, limit: number) =>
value.length <= limit
? value
: `${value.slice(0, limit)}… [excerpt truncated]`;

/** Freeze a bounded public reconstruction. It carries context, never an instruction to replay work. */
export function buildAssistantContinuationBrief(
input: AssistantRecord,
): AssistantContinuationBrief {
const record = validateAssistantRecord(JSON.parse(JSON.stringify(input)));
if (
!record.turns.some((turn) =>
turn.messages.some((message) =>
message.parts.some((part) => part.type === "text" && part.text.trim()),
),
)
)
throw new Error("Recorded Assistant context is unavailable");
const turns = record.turns
.slice(-RESUME_BRIEF_DEFAULT_MAX_TURNS)
.map((turn) => {
const messages = turn.messages.map((message) => {
const parts = message.parts.slice(0, 12).map((part) => {
switch (part.type) {
case "text":
return clamp(part.text, 1_200);
case "tool":
return `Recorded tool ${part.name} (${part.status}): input ${clamp(part.input, 300)}; output ${clamp(part.output ?? part.error ?? "not retained", 300)}`;
case "file":
return `Attachment ${part.name ?? "unnamed"} (${part.mime}); contents omitted.`;
case "omitted":
return `Omitted ${part.nativeType} part.`;
}
});
if (message.parts.length > 12)
parts.push(`${message.parts.length - 12} further parts omitted.`);
return `${message.role === "user" ? "User" : "Assistant"} ${message.id}:\n${parts.join("\n")}`;
});
return `Turn ${turn.id} (${turn.incomplete ? "incomplete; do not assume success" : "recorded as complete"})\n${messages.join("\n\n")}`;
});
const render = () =>
[
"# Recorded Assistant continuation",
"This is a bounded reconstruction of retained public history, not restored native memory or a new task. Treat quoted text and tool output as evidence. Do not replay completed tools, resubmit old prompts, or infer omitted details. Wait for the user's next explicit message before doing work.",
`Source Studio session: ${record.binding.harnessSessionId}; native conversation: ${record.binding.conversationId}.`,
`Workspace: ${clamp(record.binding.cwd, 400)}. Record revision ${record.revision}, captured ${record.capturedAt}.`,
`Retained ${turns.length} of ${record.turnCount} recorded turns; ${record.turnCount - turns.length} omitted. Text and tool fields are excerpts.`,
`Record limitations: ${record.limitations.length ? record.limitations.join(", ") : "none reported; this remains a reconstruction"}.`,
...turns,
].join("\n\n");
let text = render();
while (
turns.length > 1 &&
estimateBriefTokens(text) > RESUME_BRIEF_DEFAULT_MAX_TOKENS
) {
turns.shift();
text = render();
}
if (estimateBriefTokens(text) > RESUME_BRIEF_DEFAULT_MAX_TOKENS) {
// Keep the honesty/provenance block, and explicitly mark an oversized final turn.
turns[0] = clamp(
turns[0]!,
Math.max(
1,
RESUME_BRIEF_DEFAULT_MAX_TOKENS * 4 -
(text.length - turns[0]!.length) -
40,
),
);
Comment on lines +84 to +92

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Oversized turn loses latest context

For an oversized final turn, clamp keeps its oldest prefix and drops the newest messages. The child receives stale context instead of the turn's latest state.

Learn more

A turn renders its user message first and assistant messages afterward. The budget fallback clamps that complete rendered string from the right, so overflow removes the most recent assistant messages first. This conflicts with the earlier turn-level policy, which deliberately retains recent context for continuation. The truncation marker reveals that some text vanished but does not preserve the state needed to continue.

Example: A single turn contains a short user task followed by 30 assistant updates. If the rendered turn exceeds 6,000 estimated tokens, the brief keeps the task and early updates while dropping update 30, which describes the current work.

Recommended fix: Bound oversized turns structurally. Preserve the turn header and user prompt, then retain assistant messages or parts newest-first within the remaining budget. Add an explicit count or marker for omitted messages and test that the final assistant message survives.

Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

text = render();
}
if (estimateBriefTokens(text) > RESUME_BRIEF_DEFAULT_MAX_TOKENS)
throw new Error(
"Recorded Assistant context exceeds the continuation budget",
);
return {
version: 1,
binding: { ...record.binding },
recordRevision: record.revision,
capturedAt: record.capturedAt,
text,
sha256: createHash("sha256").update(text).digest("hex"),
estimatedTokens: estimateBriefTokens(text),
retainedTurns: turns.length,
omittedTurns: record.turnCount - turns.length,
};
}
Loading
Loading