@xopcai/xopc 0.0.103 → 0.0.105

package/dist/src/session/session-context-for-llm.d.ts

@@ -16,8 +16,100 @@ export interface XopcTranscriptContextEntry {
     data?: Record<string, unknown>;
     createdAt?: string;
 }
-export type TranscriptStoredRow = AgentMessage | XopcTranscriptContextEntry;
+/** Persisted-only row for replaying local shell executions in clients. */
+export interface XopcTranscriptBashExecutionEntry {
+    role: 'bashExecution';
+    command?: string;
+    output?: string | unknown[];
+    exitCode?: number | null;
+    signal?: string | null;
+    excludeFromContext?: boolean;
+    excludedFromContext?: boolean;
+    truncated?: boolean;
+    fullOutputPath?: string;
+    timestamp?: string | number;
+}
+/** Persisted extension-injected message row for client replay. */
+export interface XopcTranscriptCustomMessageEntry {
+    role: 'custom';
+    customType?: string;
+    content?: string | unknown[];
+    display?: boolean;
+    details?: unknown;
+    timestamp?: string | number;
+}
+/** Persisted extension custom_message entry shape before conversion to an agent message. */
+export interface XopcTranscriptCustomMessageFileEntry {
+    type: 'custom_message';
+    customType?: string;
+    content?: string | unknown[];
+    display?: boolean;
+    details?: unknown;
+    timestamp?: string | number;
+}
+/** Persisted extension state entry for replay by extension sessionManager APIs. */
+export interface XopcTranscriptCustomStateEntry {
+    type: 'custom';
+    customType?: string;
+    data?: unknown;
+    timestamp?: string | number;
+}
+/** Persisted branch summary row generated when returning from a branch. */
+export interface XopcTranscriptBranchSummaryEntry {
+    role: 'branchSummary';
+    summary?: string;
+    fromId?: string;
+    timestamp?: string | number;
+}
+/** Persisted compaction summary row generated after transcript compaction. */
+export interface XopcTranscriptCompactionSummaryEntry {
+    role: 'compactionSummary';
+    summary?: string;
+    tokensBefore?: number;
+    timestamp?: string | number;
+}
+/** Persisted label change for a transcript entry. */
+export interface XopcTranscriptLabelEntry {
+    type: 'label';
+    id?: string;
+    parentId?: string | null;
+    targetId?: string;
+    label?: string;
+    timestamp?: string | number;
+}
+/** Persisted thinking level change metadata row. */
+export interface XopcTranscriptThinkingLevelChangeEntry {
+    type: 'thinking_level_change';
+    id?: string;
+    parentId?: string | null;
+    thinkingLevel?: string;
+    timestamp?: string | number;
+}
+/** Persisted model change metadata row. */
+export interface XopcTranscriptModelChangeEntry {
+    type: 'model_change';
+    id?: string;
+    parentId?: string | null;
+    provider?: string;
+    modelId?: string;
+    timestamp?: string | number;
+}
+/** Persisted session info metadata row. */
+export interface XopcTranscriptSessionInfoEntry {
+    type: 'session_info';
+    id?: string;
+    parentId?: string | null;
+    name?: string;
+    timestamp?: string | number;
+}
+export type TranscriptStoredRow = AgentMessage | XopcTranscriptContextEntry | XopcTranscriptBashExecutionEntry | XopcTranscriptCustomMessageEntry | XopcTranscriptCustomMessageFileEntry | XopcTranscriptCustomStateEntry | XopcTranscriptBranchSummaryEntry | XopcTranscriptCompactionSummaryEntry | XopcTranscriptLabelEntry | XopcTranscriptThinkingLevelChangeEntry | XopcTranscriptModelChangeEntry | XopcTranscriptSessionInfoEntry;
 export declare function isTranscriptContextEntry(x: unknown): x is XopcTranscriptContextEntry;
+export declare function isTranscriptBashExecutionEntry(x: unknown): x is XopcTranscriptBashExecutionEntry;
+export declare function isTranscriptCustomMessageEntry(x: unknown): x is XopcTranscriptCustomMessageEntry | XopcTranscriptCustomMessageFileEntry;
+export declare function isTranscriptCustomStateEntry(x: unknown): x is XopcTranscriptCustomStateEntry;
+export declare function isTranscriptSummaryMessageEntry(x: unknown): x is XopcTranscriptBranchSummaryEntry | XopcTranscriptCompactionSummaryEntry;
+export declare function isTranscriptLabelEntry(x: unknown): x is XopcTranscriptLabelEntry;
+export declare function isTranscriptMetadataEntry(x: unknown): x is XopcTranscriptThinkingLevelChangeEntry | XopcTranscriptModelChangeEntry | XopcTranscriptSessionInfoEntry;
 /**
  * Normalize a JSON array from on-disk transcript into stored rows (drops unrecognized objects).
  */

package/dist/src/session/session-context-for-llm.js

@@ -3,6 +3,33 @@ function isTranscriptContextEntry(x) {
 	if (!x || typeof x !== "object") return false;
 	return x.kind === "context";
 }
+function isTranscriptBashExecutionEntry(x) {
+	if (!x || typeof x !== "object") return false;
+	return x.role === "bashExecution";
+}
+function isTranscriptCustomMessageEntry(x) {
+	if (!x || typeof x !== "object") return false;
+	const row = x;
+	return row.role === "custom" || row.type === "custom_message";
+}
+function isTranscriptCustomStateEntry(x) {
+	if (!x || typeof x !== "object") return false;
+	return x.type === "custom";
+}
+function isTranscriptSummaryMessageEntry(x) {
+	if (!x || typeof x !== "object") return false;
+	const role = x.role;
+	return role === "branchSummary" || role === "compactionSummary";
+}
+function isTranscriptLabelEntry(x) {
+	if (!x || typeof x !== "object") return false;
+	return x.type === "label";
+}
+function isTranscriptMetadataEntry(x) {
+	if (!x || typeof x !== "object") return false;
+	const type = x.type;
+	return type === "thinking_level_change" || type === "model_change" || type === "session_info";
+}
 const LLM_ROLES = new Set([
 	"user",
 	"assistant",
@@ -15,6 +42,49 @@ function isLikelyAgentMessage(x) {
 	const role = x.role;
 	return typeof role === "string" && LLM_ROLES.has(role);
 }
+function parseTimestampValue(timestamp) {
+	if (typeof timestamp === "number") return Number.isFinite(timestamp) ? timestamp : void 0;
+	if (typeof timestamp !== "string") return;
+	const ms = Date.parse(timestamp);
+	return Number.isFinite(ms) ? ms : void 0;
+}
+function customMessageRowToLlmMessage(row) {
+	return {
+		role: "user",
+		content: typeof row.content === "string" ? [{
+			type: "text",
+			text: row.content
+		}] : Array.isArray(row.content) ? row.content : [{
+			type: "text",
+			text: ""
+		}],
+		timestamp: parseTimestampValue(row.timestamp)
+	};
+}
+function bashExecutionRowToLlmMessage(row) {
+	if (row.excludeFromContext === true || row.excludedFromContext === true) return null;
+	const command = row.command?.trim();
+	if (!command) return null;
+	const output = typeof row.output === "string" ? row.output : Array.isArray(row.output) ? row.output.filter((part) => typeof part === "object" && part !== null && "type" in part).map((part) => part.type === "text" && typeof part.text === "string" ? part.text : "").join("") : "";
+	const exit = row.exitCode == null ? "?" : String(row.exitCode);
+	const signal = row.signal ? ` signal=${row.signal}` : "";
+	const truncated = row.truncated ? "\n[output truncated]" : "";
+	return {
+		role: "user",
+		content: [{
+			type: "text",
+			text: [
+				"<local_shell>",
+				`$ ${command}`,
+				`exit=${exit}${signal}`,
+				output ? "output:" : "output: (empty)",
+				output.trimEnd(),
+				`${truncated}</local_shell>`
+			].join("\n")
+		}],
+		timestamp: parseTimestampValue(row.timestamp)
+	};
+}
 /**
 * Normalize a JSON array from on-disk transcript into stored rows (drops unrecognized objects).
 */
@@ -25,6 +95,30 @@ function transcriptRowsFromJsonArray(arr) {
 			out.push(x);
 			continue;
 		}
+		if (isTranscriptBashExecutionEntry(x)) {
+			out.push(x);
+			continue;
+		}
+		if (isTranscriptCustomMessageEntry(x)) {
+			out.push(x);
+			continue;
+		}
+		if (isTranscriptCustomStateEntry(x)) {
+			out.push(x);
+			continue;
+		}
+		if (isTranscriptSummaryMessageEntry(x)) {
+			out.push(x);
+			continue;
+		}
+		if (isTranscriptLabelEntry(x)) {
+			out.push(x);
+			continue;
+		}
+		if (isTranscriptMetadataEntry(x)) {
+			out.push(x);
+			continue;
+		}
 		if (isLikelyAgentMessage(x)) out.push(x);
 	}
 	return out;
@@ -35,6 +129,15 @@ function buildSessionContextForLlm(rows) {
 	for (const r of rows) {
 		if (isTranscriptContextEntry(r)) continue;
 		if (r.type === "compaction") continue;
+		if (isTranscriptBashExecutionEntry(r)) {
+			const msg = bashExecutionRowToLlmMessage(r);
+			if (msg) out.push(msg);
+			continue;
+		}
+		if (isTranscriptCustomMessageEntry(r)) {
+			out.push(customMessageRowToLlmMessage(r));
+			continue;
+		}
 		if (isLikelyAgentMessage(r)) out.push(r);
 	}
 	return out;
@@ -47,7 +150,7 @@ function buildSessionContextForLlm(rows) {
 function mergeLlmMessagesPreservingContextRows(prevRows, llmMessages) {
 	let i = 0;
 	const out = [];
-	for (const r of prevRows) if (isTranscriptContextEntry(r)) out.push(r);
+	for (const r of prevRows) if (isTranscriptContextEntry(r) || isTranscriptBashExecutionEntry(r) || isTranscriptCustomMessageEntry(r) || isTranscriptCustomStateEntry(r) || isTranscriptSummaryMessageEntry(r) || isTranscriptLabelEntry(r) || isTranscriptMetadataEntry(r)) out.push(r);
 	else if (i < llmMessages.length) {
 		out.push(llmMessages[i]);
 		i += 1;
@@ -59,6 +162,6 @@ function mergeLlmMessagesPreservingContextRows(prevRows, llmMessages) {
 	return out;
 }
 //#endregion
-export { buildSessionContextForLlm, isTranscriptContextEntry, mergeLlmMessagesPreservingContextRows, transcriptRowsFromJsonArray };
+export { buildSessionContextForLlm, isTranscriptBashExecutionEntry, isTranscriptContextEntry, isTranscriptCustomMessageEntry, isTranscriptCustomStateEntry, isTranscriptLabelEntry, isTranscriptMetadataEntry, isTranscriptSummaryMessageEntry, mergeLlmMessagesPreservingContextRows, transcriptRowsFromJsonArray };
 
 //# sourceMappingURL=session-context-for-llm.js.map

package/dist/src/session/session-context-for-llm.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-context-for-llm.js","names":[],"sources":["../../../src/session/session-context-for-llm.ts"],"sourcesContent":["/**\n * Transcript rows persisted on disk may include non-LLM entries (e.g. `kind: 'context'`).\n * {@link buildSessionContextForLlm} is the single choke point for provider-facing history.\n *\n * Do not pass raw on-disk JSONL rows into pi-agent / providers — always run\n * {@link buildSessionContextForLlm} first (or use {@link SessionStore.loadMessages}, which already does).\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\n\n/** Persisted-only row: never sent to the model as a chat message. */\nexport interface XopcTranscriptContextEntry {\n  kind: 'context';\n  id?: string;\n  /** Short human-readable line for UIs / logs. */\n  text?: string;\n  /** Structured payload (tool summaries, delivery metadata, etc.). */\n  data?: Record<string, unknown>;\n  createdAt?: string;\n}\n\nexport type TranscriptStoredRow = AgentMessage | XopcTranscriptContextEntry;\n\nexport function isTranscriptContextEntry(x: unknown): x is XopcTranscriptContextEntry {\n  if (!x || typeof x !== 'object') return false;\n  return (x as Record<string, unknown>).kind === 'context';\n}\n\nconst LLM_ROLES = new Set(['user', 'assistant', 'system', 'tool', 'toolResult']);\n\nfunction isLikelyAgentMessage(x: unknown): x is AgentMessage {\n  if (!x || typeof x !== 'object') return false;\n  const role = (x as Record<string, unknown>).role;\n  return typeof role === 'string' && LLM_ROLES.has(role);\n}\n\n/**\n * Normalize a JSON array from on-disk transcript into stored rows (drops unrecognized objects).\n */\nexport function transcriptRowsFromJsonArray(arr: unknown[]): TranscriptStoredRow[] {\n  const out: TranscriptStoredRow[] = [];\n  for (const x of arr) {\n    if (isTranscriptContextEntry(x)) {\n      out.push(x);\n      continue;\n    }\n    if (isLikelyAgentMessage(x)) {\n      out.push(x);\n    }\n  }\n  return out;\n}\n\n/** Messages only — what providers and pi-agent should see. */\nexport function buildSessionContextForLlm(rows: TranscriptStoredRow[]): AgentMessage[] {\n  const out: AgentMessage[] = [];\n  for (const r of rows) {\n    if (isTranscriptContextEntry(r)) {\n      continue;\n    }\n    if ((r as { type?: string }).type === 'compaction') {\n      continue;\n    }\n    if (isLikelyAgentMessage(r)) {\n      out.push(r);\n    }\n  }\n  return out;\n}\n\n/**\n * When persisting LLM messages, keep prior `kind: 'context'` rows in their relative positions:\n * each non-context slot in the previous file is replaced by the next incoming LLM message;\n * trailing new LLM rows are appended. Extra old LLM rows are dropped if the new list is shorter.\n */\nexport function mergeLlmMessagesPreservingContextRows(\n  prevRows: TranscriptStoredRow[],\n  llmMessages: AgentMessage[],\n): TranscriptStoredRow[] {\n  let i = 0;\n  const out: TranscriptStoredRow[] = [];\n  for (const r of prevRows) {\n    if (isTranscriptContextEntry(r)) {\n      out.push(r);\n    } else {\n      if (i < llmMessages.length) {\n        out.push(llmMessages[i]);\n        i += 1;\n      }\n    }\n  }\n  while (i < llmMessages.length) {\n    out.push(llmMessages[i]);\n    i += 1;\n  }\n  return out;\n}\n"],"mappings":";AAuBA,SAAgB,yBAAyB,GAA6C;AACpF,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,QAAQ,EAA8B,SAAS;;AAGjD,MAAM,YAAY,IAAI,IAAI;CAAC;CAAQ;CAAa;CAAU;CAAQ;CAAa,CAAC;AAEhF,SAAS,qBAAqB,GAA+B;AAC3D,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;CACxC,MAAM,OAAQ,EAA8B;AAC5C,QAAO,OAAO,SAAS,YAAY,UAAU,IAAI,KAAK;;;;;AAMxD,SAAgB,4BAA4B,KAAuC;CACjF,MAAM,MAA6B,EAAE;AACrC,MAAK,MAAM,KAAK,KAAK;AACnB,MAAI,yBAAyB,EAAE,EAAE;AAC/B,OAAI,KAAK,EAAE;AACX;;AAEF,MAAI,qBAAqB,EAAE,CACzB,KAAI,KAAK,EAAE;;AAGf,QAAO;;;AAIT,SAAgB,0BAA0B,MAA6C;CACrF,MAAM,MAAsB,EAAE;AAC9B,MAAK,MAAM,KAAK,MAAM;AACpB,MAAI,yBAAyB,EAAE,CAC7B;AAEF,MAAK,EAAwB,SAAS,aACpC;AAEF,MAAI,qBAAqB,EAAE,CACzB,KAAI,KAAK,EAAE;;AAGf,QAAO;;;;;;;AAQT,SAAgB,sCACd,UACA,aACuB;CACvB,IAAI,IAAI;CACR,MAAM,MAA6B,EAAE;AACrC,MAAK,MAAM,KAAK,SACd,KAAI,yBAAyB,EAAE,CAC7B,KAAI,KAAK,EAAE;UAEP,IAAI,YAAY,QAAQ;AAC1B,MAAI,KAAK,YAAY,GAAG;AACxB,OAAK;;AAIX,QAAO,IAAI,YAAY,QAAQ;AAC7B,MAAI,KAAK,YAAY,GAAG;AACxB,OAAK;;AAEP,QAAO"}
+{"version":3,"file":"session-context-for-llm.js","names":[],"sources":["../../../src/session/session-context-for-llm.ts"],"sourcesContent":["/**\n * Transcript rows persisted on disk may include non-LLM entries (e.g. `kind: 'context'`).\n * {@link buildSessionContextForLlm} is the single choke point for provider-facing history.\n *\n * Do not pass raw on-disk JSONL rows into pi-agent / providers — always run\n * {@link buildSessionContextForLlm} first (or use {@link SessionStore.loadMessages}, which already does).\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\n\n/** Persisted-only row: never sent to the model as a chat message. */\nexport interface XopcTranscriptContextEntry {\n  kind: 'context';\n  id?: string;\n  /** Short human-readable line for UIs / logs. */\n  text?: string;\n  /** Structured payload (tool summaries, delivery metadata, etc.). */\n  data?: Record<string, unknown>;\n  createdAt?: string;\n}\n\n/** Persisted-only row for replaying local shell executions in clients. */\nexport interface XopcTranscriptBashExecutionEntry {\n  role: 'bashExecution';\n  command?: string;\n  output?: string | unknown[];\n  exitCode?: number | null;\n  signal?: string | null;\n  excludeFromContext?: boolean;\n  excludedFromContext?: boolean;\n  truncated?: boolean;\n  fullOutputPath?: string;\n  timestamp?: string | number;\n}\n\n/** Persisted extension-injected message row for client replay. */\nexport interface XopcTranscriptCustomMessageEntry {\n  role: 'custom';\n  customType?: string;\n  content?: string | unknown[];\n  display?: boolean;\n  details?: unknown;\n  timestamp?: string | number;\n}\n\n/** Persisted extension custom_message entry shape before conversion to an agent message. */\nexport interface XopcTranscriptCustomMessageFileEntry {\n  type: 'custom_message';\n  customType?: string;\n  content?: string | unknown[];\n  display?: boolean;\n  details?: unknown;\n  timestamp?: string | number;\n}\n\n/** Persisted extension state entry for replay by extension sessionManager APIs. */\nexport interface XopcTranscriptCustomStateEntry {\n  type: 'custom';\n  customType?: string;\n  data?: unknown;\n  timestamp?: string | number;\n}\n\n/** Persisted branch summary row generated when returning from a branch. */\nexport interface XopcTranscriptBranchSummaryEntry {\n  role: 'branchSummary';\n  summary?: string;\n  fromId?: string;\n  timestamp?: string | number;\n}\n\n/** Persisted compaction summary row generated after transcript compaction. */\nexport interface XopcTranscriptCompactionSummaryEntry {\n  role: 'compactionSummary';\n  summary?: string;\n  tokensBefore?: number;\n  timestamp?: string | number;\n}\n\n/** Persisted label change for a transcript entry. */\nexport interface XopcTranscriptLabelEntry {\n  type: 'label';\n  id?: string;\n  parentId?: string | null;\n  targetId?: string;\n  label?: string;\n  timestamp?: string | number;\n}\n\n/** Persisted thinking level change metadata row. */\nexport interface XopcTranscriptThinkingLevelChangeEntry {\n  type: 'thinking_level_change';\n  id?: string;\n  parentId?: string | null;\n  thinkingLevel?: string;\n  timestamp?: string | number;\n}\n\n/** Persisted model change metadata row. */\nexport interface XopcTranscriptModelChangeEntry {\n  type: 'model_change';\n  id?: string;\n  parentId?: string | null;\n  provider?: string;\n  modelId?: string;\n  timestamp?: string | number;\n}\n\n/** Persisted session info metadata row. */\nexport interface XopcTranscriptSessionInfoEntry {\n  type: 'session_info';\n  id?: string;\n  parentId?: string | null;\n  name?: string;\n  timestamp?: string | number;\n}\n\nexport type TranscriptStoredRow =\n  | AgentMessage\n  | XopcTranscriptContextEntry\n  | XopcTranscriptBashExecutionEntry\n  | XopcTranscriptCustomMessageEntry\n  | XopcTranscriptCustomMessageFileEntry\n  | XopcTranscriptCustomStateEntry\n  | XopcTranscriptBranchSummaryEntry\n  | XopcTranscriptCompactionSummaryEntry\n  | XopcTranscriptLabelEntry\n  | XopcTranscriptThinkingLevelChangeEntry\n  | XopcTranscriptModelChangeEntry\n  | XopcTranscriptSessionInfoEntry;\n\nexport function isTranscriptContextEntry(x: unknown): x is XopcTranscriptContextEntry {\n  if (!x || typeof x !== 'object') return false;\n  return (x as Record<string, unknown>).kind === 'context';\n}\n\nexport function isTranscriptBashExecutionEntry(x: unknown): x is XopcTranscriptBashExecutionEntry {\n  if (!x || typeof x !== 'object') return false;\n  return (x as Record<string, unknown>).role === 'bashExecution';\n}\n\nexport function isTranscriptCustomMessageEntry(\n  x: unknown,\n): x is XopcTranscriptCustomMessageEntry | XopcTranscriptCustomMessageFileEntry {\n  if (!x || typeof x !== 'object') return false;\n  const row = x as Record<string, unknown>;\n  return row.role === 'custom' || row.type === 'custom_message';\n}\n\nexport function isTranscriptCustomStateEntry(x: unknown): x is XopcTranscriptCustomStateEntry {\n  if (!x || typeof x !== 'object') return false;\n  return (x as Record<string, unknown>).type === 'custom';\n}\n\nexport function isTranscriptSummaryMessageEntry(\n  x: unknown,\n): x is XopcTranscriptBranchSummaryEntry | XopcTranscriptCompactionSummaryEntry {\n  if (!x || typeof x !== 'object') return false;\n  const role = (x as Record<string, unknown>).role;\n  return role === 'branchSummary' || role === 'compactionSummary';\n}\n\nexport function isTranscriptLabelEntry(x: unknown): x is XopcTranscriptLabelEntry {\n  if (!x || typeof x !== 'object') return false;\n  return (x as Record<string, unknown>).type === 'label';\n}\n\nexport function isTranscriptMetadataEntry(\n  x: unknown,\n): x is XopcTranscriptThinkingLevelChangeEntry | XopcTranscriptModelChangeEntry | XopcTranscriptSessionInfoEntry {\n  if (!x || typeof x !== 'object') return false;\n  const type = (x as Record<string, unknown>).type;\n  return type === 'thinking_level_change' || type === 'model_change' || type === 'session_info';\n}\n\nconst LLM_ROLES = new Set(['user', 'assistant', 'system', 'tool', 'toolResult']);\n\nfunction isLikelyAgentMessage(x: unknown): x is AgentMessage {\n  if (!x || typeof x !== 'object') return false;\n  const role = (x as Record<string, unknown>).role;\n  return typeof role === 'string' && LLM_ROLES.has(role);\n}\n\nfunction parseTimestampValue(timestamp: string | number | undefined): number | undefined {\n  if (typeof timestamp === 'number') {\n    return Number.isFinite(timestamp) ? timestamp : undefined;\n  }\n  if (typeof timestamp !== 'string') {\n    return undefined;\n  }\n  const ms = Date.parse(timestamp);\n  return Number.isFinite(ms) ? ms : undefined;\n}\n\nfunction customMessageRowToLlmMessage(\n  row: XopcTranscriptCustomMessageEntry | XopcTranscriptCustomMessageFileEntry,\n): AgentMessage {\n  const content = typeof row.content === 'string'\n    ? [{ type: 'text' as const, text: row.content }]\n    : Array.isArray(row.content)\n      ? row.content\n      : [{ type: 'text' as const, text: '' }];\n  return {\n    role: 'user',\n    content,\n    timestamp: parseTimestampValue(row.timestamp),\n  } as AgentMessage;\n}\n\nfunction bashExecutionRowToLlmMessage(row: XopcTranscriptBashExecutionEntry): AgentMessage | null {\n  if (row.excludeFromContext === true || row.excludedFromContext === true) {\n    return null;\n  }\n  const command = row.command?.trim();\n  if (!command) {\n    return null;\n  }\n  const output = typeof row.output === 'string'\n    ? row.output\n    : Array.isArray(row.output)\n      ? row.output\n        .filter((part): part is { type: string; text?: string } =>\n          typeof part === 'object' && part !== null && 'type' in part)\n        .map((part) => (part.type === 'text' && typeof part.text === 'string' ? part.text : ''))\n        .join('')\n      : '';\n  const exit = row.exitCode == null ? '?' : String(row.exitCode);\n  const signal = row.signal ? ` signal=${row.signal}` : '';\n  const truncated = row.truncated ? '\\n[output truncated]' : '';\n  return {\n    role: 'user',\n    content: [{\n      type: 'text',\n      text: [\n        '<local_shell>',\n        `$ ${command}`,\n        `exit=${exit}${signal}`,\n        output ? 'output:' : 'output: (empty)',\n        output.trimEnd(),\n        `${truncated}</local_shell>`,\n      ].join('\\n'),\n    }],\n    timestamp: parseTimestampValue(row.timestamp),\n  } as AgentMessage;\n}\n\n/**\n * Normalize a JSON array from on-disk transcript into stored rows (drops unrecognized objects).\n */\nexport function transcriptRowsFromJsonArray(arr: unknown[]): TranscriptStoredRow[] {\n  const out: TranscriptStoredRow[] = [];\n  for (const x of arr) {\n    if (isTranscriptContextEntry(x)) {\n      out.push(x);\n      continue;\n    }\n    if (isTranscriptBashExecutionEntry(x)) {\n      out.push(x);\n      continue;\n    }\n    if (isTranscriptCustomMessageEntry(x)) {\n      out.push(x);\n      continue;\n    }\n    if (isTranscriptCustomStateEntry(x)) {\n      out.push(x);\n      continue;\n    }\n    if (isTranscriptSummaryMessageEntry(x)) {\n      out.push(x);\n      continue;\n    }\n    if (isTranscriptLabelEntry(x)) {\n      out.push(x);\n      continue;\n    }\n    if (isTranscriptMetadataEntry(x)) {\n      out.push(x);\n      continue;\n    }\n    if (isLikelyAgentMessage(x)) {\n      out.push(x);\n    }\n  }\n  return out;\n}\n\n/** Messages only — what providers and pi-agent should see. */\nexport function buildSessionContextForLlm(rows: TranscriptStoredRow[]): AgentMessage[] {\n  const out: AgentMessage[] = [];\n  for (const r of rows) {\n    if (isTranscriptContextEntry(r)) {\n      continue;\n    }\n    if ((r as { type?: string }).type === 'compaction') {\n      continue;\n    }\n    if (isTranscriptBashExecutionEntry(r)) {\n      const msg = bashExecutionRowToLlmMessage(r);\n      if (msg) out.push(msg);\n      continue;\n    }\n    if (isTranscriptCustomMessageEntry(r)) {\n      out.push(customMessageRowToLlmMessage(r));\n      continue;\n    }\n    if (isLikelyAgentMessage(r)) {\n      out.push(r);\n    }\n  }\n  return out;\n}\n\n/**\n * When persisting LLM messages, keep prior `kind: 'context'` rows in their relative positions:\n * each non-context slot in the previous file is replaced by the next incoming LLM message;\n * trailing new LLM rows are appended. Extra old LLM rows are dropped if the new list is shorter.\n */\nexport function mergeLlmMessagesPreservingContextRows(\n  prevRows: TranscriptStoredRow[],\n  llmMessages: AgentMessage[],\n): TranscriptStoredRow[] {\n  let i = 0;\n  const out: TranscriptStoredRow[] = [];\n  for (const r of prevRows) {\n    if (\n      isTranscriptContextEntry(r) ||\n      isTranscriptBashExecutionEntry(r) ||\n      isTranscriptCustomMessageEntry(r) ||\n      isTranscriptCustomStateEntry(r) ||\n      isTranscriptSummaryMessageEntry(r) ||\n      isTranscriptLabelEntry(r) ||\n      isTranscriptMetadataEntry(r)\n    ) {\n      out.push(r);\n    } else {\n      if (i < llmMessages.length) {\n        out.push(llmMessages[i]);\n        i += 1;\n      }\n    }\n  }\n  while (i < llmMessages.length) {\n    out.push(llmMessages[i]);\n    i += 1;\n  }\n  return out;\n}\n"],"mappings":";AAmIA,SAAgB,yBAAyB,GAA6C;AACpF,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,QAAQ,EAA8B,SAAS;;AAGjD,SAAgB,+BAA+B,GAAmD;AAChG,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,QAAQ,EAA8B,SAAS;;AAGjD,SAAgB,+BACd,GAC8E;AAC9E,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;CACxC,MAAM,MAAM;AACZ,QAAO,IAAI,SAAS,YAAY,IAAI,SAAS;;AAG/C,SAAgB,6BAA6B,GAAiD;AAC5F,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,QAAQ,EAA8B,SAAS;;AAGjD,SAAgB,gCACd,GAC8E;AAC9E,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;CACxC,MAAM,OAAQ,EAA8B;AAC5C,QAAO,SAAS,mBAAmB,SAAS;;AAG9C,SAAgB,uBAAuB,GAA2C;AAChF,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,QAAQ,EAA8B,SAAS;;AAGjD,SAAgB,0BACd,GAC+G;AAC/G,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;CACxC,MAAM,OAAQ,EAA8B;AAC5C,QAAO,SAAS,2BAA2B,SAAS,kBAAkB,SAAS;;AAGjF,MAAM,YAAY,IAAI,IAAI;CAAC;CAAQ;CAAa;CAAU;CAAQ;CAAa,CAAC;AAEhF,SAAS,qBAAqB,GAA+B;AAC3D,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;CACxC,MAAM,OAAQ,EAA8B;AAC5C,QAAO,OAAO,SAAS,YAAY,UAAU,IAAI,KAAK;;AAGxD,SAAS,oBAAoB,WAA4D;AACvF,KAAI,OAAO,cAAc,SACvB,QAAO,OAAO,SAAS,UAAU,GAAG,YAAY,KAAA;AAElD,KAAI,OAAO,cAAc,SACvB;CAEF,MAAM,KAAK,KAAK,MAAM,UAAU;AAChC,QAAO,OAAO,SAAS,GAAG,GAAG,KAAK,KAAA;;AAGpC,SAAS,6BACP,KACc;AAMd,QAAO;EACL,MAAM;EACN,SAPc,OAAO,IAAI,YAAY,WACnC,CAAC;GAAE,MAAM;GAAiB,MAAM,IAAI;GAAS,CAAC,GAC9C,MAAM,QAAQ,IAAI,QAAQ,GACxB,IAAI,UACJ,CAAC;GAAE,MAAM;GAAiB,MAAM;GAAI,CAAC;EAIzC,WAAW,oBAAoB,IAAI,UAAU;EAC9C;;AAGH,SAAS,6BAA6B,KAA4D;AAChG,KAAI,IAAI,uBAAuB,QAAQ,IAAI,wBAAwB,KACjE,QAAO;CAET,MAAM,UAAU,IAAI,SAAS,MAAM;AACnC,KAAI,CAAC,QACH,QAAO;CAET,MAAM,SAAS,OAAO,IAAI,WAAW,WACjC,IAAI,SACJ,MAAM,QAAQ,IAAI,OAAO,GACvB,IAAI,OACH,QAAQ,SACP,OAAO,SAAS,YAAY,SAAS,QAAQ,UAAU,KAAK,CAC7D,KAAK,SAAU,KAAK,SAAS,UAAU,OAAO,KAAK,SAAS,WAAW,KAAK,OAAO,GAAI,CACvF,KAAK,GAAG,GACT;CACN,MAAM,OAAO,IAAI,YAAY,OAAO,MAAM,OAAO,IAAI,SAAS;CAC9D,MAAM,SAAS,IAAI,SAAS,WAAW,IAAI,WAAW;CACtD,MAAM,YAAY,IAAI,YAAY,yBAAyB;AAC3D,QAAO;EACL,MAAM;EACN,SAAS,CAAC;GACR,MAAM;GACN,MAAM;IACJ;IACA,KAAK;IACL,QAAQ,OAAO;IACf,SAAS,YAAY;IACrB,OAAO,SAAS;IAChB,GAAG,UAAU;IACd,CAAC,KAAK,KAAK;GACb,CAAC;EACF,WAAW,oBAAoB,IAAI,UAAU;EAC9C;;;;;AAMH,SAAgB,4BAA4B,KAAuC;CACjF,MAAM,MAA6B,EAAE;AACrC,MAAK,MAAM,KAAK,KAAK;AACnB,MAAI,yBAAyB,EAAE,EAAE;AAC/B,OAAI,KAAK,EAAE;AACX;;AAEF,MAAI,+BAA+B,EAAE,EAAE;AACrC,OAAI,KAAK,EAAE;AACX;;AAEF,MAAI,+BAA+B,EAAE,EAAE;AACrC,OAAI,KAAK,EAAE;AACX;;AAEF,MAAI,6BAA6B,EAAE,EAAE;AACnC,OAAI,KAAK,EAAE;AACX;;AAEF,MAAI,gCAAgC,EAAE,EAAE;AACtC,OAAI,KAAK,EAAE;AACX;;AAEF,MAAI,uBAAuB,EAAE,EAAE;AAC7B,OAAI,KAAK,EAAE;AACX;;AAEF,MAAI,0BAA0B,EAAE,EAAE;AAChC,OAAI,KAAK,EAAE;AACX;;AAEF,MAAI,qBAAqB,EAAE,CACzB,KAAI,KAAK,EAAE;;AAGf,QAAO;;;AAIT,SAAgB,0BAA0B,MAA6C;CACrF,MAAM,MAAsB,EAAE;AAC9B,MAAK,MAAM,KAAK,MAAM;AACpB,MAAI,yBAAyB,EAAE,CAC7B;AAEF,MAAK,EAAwB,SAAS,aACpC;AAEF,MAAI,+BAA+B,EAAE,EAAE;GACrC,MAAM,MAAM,6BAA6B,EAAE;AAC3C,OAAI,IAAK,KAAI,KAAK,IAAI;AACtB;;AAEF,MAAI,+BAA+B,EAAE,EAAE;AACrC,OAAI,KAAK,6BAA6B,EAAE,CAAC;AACzC;;AAEF,MAAI,qBAAqB,EAAE,CACzB,KAAI,KAAK,EAAE;;AAGf,QAAO;;;;;;;AAQT,SAAgB,sCACd,UACA,aACuB;CACvB,IAAI,IAAI;CACR,MAAM,MAA6B,EAAE;AACrC,MAAK,MAAM,KAAK,SACd,KACE,yBAAyB,EAAE,IAC3B,+BAA+B,EAAE,IACjC,+BAA+B,EAAE,IACjC,6BAA6B,EAAE,IAC/B,gCAAgC,EAAE,IAClC,uBAAuB,EAAE,IACzB,0BAA0B,EAAE,CAE5B,KAAI,KAAK,EAAE;UAEP,IAAI,YAAY,QAAQ;AAC1B,MAAI,KAAK,YAAY,GAAG;AACxB,OAAK;;AAIX,QAAO,IAAI,YAAY,QAAQ;AAC7B,MAAI,KAAK,YAAY,GAAG;AACxB,OAAK;;AAEP,QAAO"}

package/dist/src/session/store.d.ts

@@ -76,6 +76,29 @@ export declare class SessionStore {
     loadTranscriptDocument(key: string): Promise<XopcSessionTranscriptV1 | null>;
     syncEmbeddedTranscriptUpdate(update: SessionTranscriptUpdate): Promise<void>;
     appendTranscriptContextEntry(key: string, entry: Omit<XopcTranscriptContextEntry, 'kind'> & Partial<Pick<XopcTranscriptContextEntry, 'kind'>>): Promise<void>;
+    appendTranscriptLabelEntry(key: string, entry: {
+        targetId: string;
+        label?: string;
+    }): Promise<void>;
+    appendTranscriptCustomEntry(key: string, entry: {
+        customType: string;
+        data?: unknown;
+    }): Promise<void>;
+    appendTranscriptCustomMessageEntry(key: string, entry: {
+        customType: string;
+        content?: string | unknown[];
+        display?: boolean;
+        details?: unknown;
+    }): Promise<void>;
+    appendTranscriptBashExecutionEntry(key: string, entry: {
+        command: string;
+        output?: string;
+        exitCode?: number | null;
+        signal?: string | null;
+        excludeFromContext?: boolean;
+        truncated?: boolean;
+        fullOutputPath?: string;
+    }): Promise<void>;
     saveMessages(key: string, messages: AgentMessage[]): Promise<void>;
     getWindowStats(messages: AgentMessage[]): {
         total: number;
@@ -117,6 +140,20 @@ export declare class SessionStore {
     estimateTokenUsage(_key: string, messages: AgentMessage[]): Promise<number>;
     searchInSession(key: string, keyword: string): Promise<Message[]>;
     exportSession(key: string, format: ExportFormat): Promise<string>;
+    importSessionExport(targetKey: string, jsonContent: string): Promise<{
+        sessionKey: string;
+        rowCount: number;
+    }>;
+    forkSession(sourceKey: string, targetKey: string): Promise<{
+        sessionKey: string;
+        rowCount: number;
+    }>;
+    forkSessionRows(sourceKey: string, targetKey: string, options?: {
+        throughRow?: number;
+    }): Promise<{
+        sessionKey: string;
+        rowCount: number;
+    }>;
     getStats(): Promise<GlobalSessionStats>;
     archiveOld(olderThanDays: number): Promise<number>;
     estimateTokens(messages: AgentMessage[]): number;

package/dist/src/session/store.js

@@ -4,7 +4,7 @@ import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
 import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { requireXopcDatabase } from "../storage/sqlite/connection.js";
 import "./types.js";
-import { buildSessionContextForLlm, mergeLlmMessagesPreservingContextRows } from "./session-context-for-llm.js";
+import { buildSessionContextForLlm, mergeLlmMessagesPreservingContextRows, transcriptRowsFromJsonArray } from "./session-context-for-llm.js";
 import { estimateTokensFromMessages } from "../storage/sqlite/row-mappers.js";
 import { deleteSessionRecord, ensureSessionRecord, getGlobalSessionStats, getSessionMetadata, listSessionMetadata, listSessionsByAgent, patchSessionMetadata, resetSessionRecord } from "../storage/sqlite/session-repository.js";
 import { appendTranscriptEntry, captureCompactionCheckpoint, getCompactionCheckpointDetail, listCompactionCheckpoints, loadCheckpointRows, loadLlmMessagesForSession, loadTranscriptRowsForSession, replaceTranscriptRows, restoreCompactionCheckpoint } from "../storage/sqlite/transcript-repository.js";
@@ -246,6 +246,61 @@ var SessionStore = class {
 			});
 		});
 	}
+	async appendTranscriptLabelEntry(key, entry) {
+		return this.runStoreMutation(async () => {
+			requireXopcDatabase();
+			ensureSessionRecord(key, this.resolveWorkspaceCwd(key));
+			appendTranscriptEntry(key, {
+				type: "label",
+				targetId: entry.targetId,
+				label: entry.label?.trim() || void 0,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		});
+	}
+	async appendTranscriptCustomEntry(key, entry) {
+		return this.runStoreMutation(async () => {
+			requireXopcDatabase();
+			ensureSessionRecord(key, this.resolveWorkspaceCwd(key));
+			appendTranscriptEntry(key, {
+				type: "custom",
+				customType: entry.customType.trim(),
+				data: entry.data,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		});
+	}
+	async appendTranscriptCustomMessageEntry(key, entry) {
+		return this.runStoreMutation(async () => {
+			requireXopcDatabase();
+			ensureSessionRecord(key, this.resolveWorkspaceCwd(key));
+			appendTranscriptEntry(key, {
+				role: "custom",
+				customType: entry.customType.trim(),
+				content: entry.content ?? "",
+				display: entry.display ?? true,
+				details: entry.details,
+				timestamp: Date.now()
+			});
+		});
+	}
+	async appendTranscriptBashExecutionEntry(key, entry) {
+		return this.runStoreMutation(async () => {
+			requireXopcDatabase();
+			ensureSessionRecord(key, this.resolveWorkspaceCwd(key));
+			appendTranscriptEntry(key, {
+				role: "bashExecution",
+				command: entry.command,
+				output: entry.output ?? "",
+				exitCode: entry.exitCode ?? null,
+				signal: entry.signal ?? null,
+				excludeFromContext: entry.excludeFromContext === true,
+				truncated: entry.truncated === true,
+				fullOutputPath: entry.fullOutputPath,
+				timestamp: Date.now()
+			});
+		});
+	}
 	async saveMessages(key, messages) {
 		return this.runStoreMutation(async () => {
 			requireXopcDatabase();
@@ -360,6 +415,72 @@ var SessionStore = class {
 		for (const msg of messages) lines.push(`## ${msg.role}`, "", typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content), "");
 		return lines.join("\n");
 	}
+	async importSessionExport(targetKey, jsonContent) {
+		return this.runStoreMutation(async () => {
+			requireXopcDatabase();
+			if (await this.getMetadata(targetKey)) throw new Error(`Target session already exists: ${targetKey}`);
+			let parsed;
+			try {
+				parsed = JSON.parse(jsonContent);
+			} catch (err) {
+				const errorMessage = err instanceof Error ? err.message : String(err);
+				throw new Error(`Invalid session export JSON: ${errorMessage}`);
+			}
+			const record = parsed && typeof parsed === "object" ? parsed : {};
+			const rowsSource = Array.isArray(record.transcriptRows) ? record.transcriptRows : void 0;
+			const rows = rowsSource ? transcriptRowsFromJsonArray(rowsSource) : [];
+			if (rows.length === 0) throw new Error("Session export contains no importable transcript rows");
+			ensureSessionRecord(targetKey, this.resolveWorkspaceCwd(targetKey));
+			replaceTranscriptRows(targetKey, rows);
+			const metadata = record.metadata && typeof record.metadata === "object" ? record.metadata : {};
+			const sourceKey = typeof metadata.key === "string" ? metadata.key : void 0;
+			const sourceName = typeof metadata.name === "string" ? metadata.name.trim() : "";
+			patchSessionMetadata(targetKey, {
+				name: sourceName ? `Import of ${sourceName}` : "Imported session",
+				tags: [...new Set([...Array.isArray(metadata.tags) ? metadata.tags.filter((tag) => typeof tag === "string") : [], "import"])],
+				customData: {
+					...metadata.customData && typeof metadata.customData === "object" ? metadata.customData : {},
+					...sourceKey ? { importedFromSessionKey: sourceKey } : {},
+					importedAt: (/* @__PURE__ */ new Date()).toISOString()
+				}
+			});
+			return {
+				sessionKey: targetKey,
+				rowCount: rows.length
+			};
+		});
+	}
+	async forkSession(sourceKey, targetKey) {
+		return this.forkSessionRows(sourceKey, targetKey);
+	}
+	async forkSessionRows(sourceKey, targetKey, options = {}) {
+		return this.runStoreMutation(async () => {
+			requireXopcDatabase();
+			const sourceMetadata = await this.getMetadata(sourceKey);
+			if (!sourceMetadata) throw new Error(`Session not found: ${sourceKey}`);
+			if (await this.getMetadata(targetKey)) throw new Error(`Target session already exists: ${targetKey}`);
+			const rows = await this.loadTranscriptRows(sourceKey);
+			if (options.throughRow !== void 0 && (options.throughRow < 1 || options.throughRow > rows.length)) throw new Error(`Invalid fork row: ${options.throughRow}`);
+			const selectedRows = options.throughRow === void 0 ? rows : rows.slice(0, Math.max(0, Math.trunc(options.throughRow)));
+			ensureSessionRecord(targetKey, this.resolveWorkspaceCwd(targetKey));
+			replaceTranscriptRows(targetKey, selectedRows);
+			patchSessionMetadata(targetKey, {
+				name: `Fork of ${sourceMetadata.name?.trim() || sourceKey}`,
+				tags: [...new Set([...sourceMetadata.tags ?? [], "fork"])],
+				customData: {
+					...sourceMetadata.customData ?? {},
+					forkedFromSessionKey: sourceKey,
+					forkedFromTranscriptId: sourceMetadata.transcriptId,
+					...options.throughRow !== void 0 ? { forkedFromRow: selectedRows.length } : {},
+					forkedAt: (/* @__PURE__ */ new Date()).toISOString()
+				}
+			});
+			return {
+				sessionKey: targetKey,
+				rowCount: selectedRows.length
+			};
+		});
+	}
 	async getStats() {
 		requireXopcDatabase();
 		return getGlobalSessionStats();
@@ -485,10 +606,14 @@ var SessionStore = class {
 			if (rawUsage && typeof rawUsage === "object") {
 				const inputTokens = typeof rawUsage.input === "number" ? rawUsage.input : void 0;
 				const outputTokens = typeof rawUsage.output === "number" ? rawUsage.output : void 0;
+				const cacheReadTokens = typeof rawUsage.cacheRead === "number" ? rawUsage.cacheRead : void 0;
+				const cacheWriteTokens = typeof rawUsage.cacheWrite === "number" ? rawUsage.cacheWrite : void 0;
 				const totalTokens = typeof rawUsage.totalTokens === "number" ? rawUsage.totalTokens : typeof rawUsage.total === "number" ? rawUsage.total : void 0;
-				if (inputTokens !== void 0 || outputTokens !== void 0 || totalTokens !== void 0) row.usage = {
+				if (inputTokens !== void 0 || outputTokens !== void 0 || cacheReadTokens !== void 0 || cacheWriteTokens !== void 0 || totalTokens !== void 0) row.usage = {
 					inputTokens,
 					outputTokens,
+					cacheReadTokens,
+					cacheWriteTokens,
 					totalTokens
 				};
 			}