@sayknow-cli/agent-core 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/CHANGELOG.md +588 -0
  2. package/README.md +473 -0
  3. package/dist/types/agent-loop.d.ts +56 -0
  4. package/dist/types/agent.d.ts +381 -0
  5. package/dist/types/append-only-context.d.ts +124 -0
  6. package/dist/types/compaction/branch-summarization.d.ts +103 -0
  7. package/dist/types/compaction/compaction.d.ts +253 -0
  8. package/dist/types/compaction/entries.d.ts +109 -0
  9. package/dist/types/compaction/errors.d.ts +26 -0
  10. package/dist/types/compaction/index.d.ts +11 -0
  11. package/dist/types/compaction/messages.d.ts +61 -0
  12. package/dist/types/compaction/openai.d.ts +62 -0
  13. package/dist/types/compaction/pruning.d.ts +37 -0
  14. package/dist/types/compaction/utils.d.ts +32 -0
  15. package/dist/types/compaction.d.ts +1 -0
  16. package/dist/types/harmony-leak.d.ts +99 -0
  17. package/dist/types/index.d.ts +10 -0
  18. package/dist/types/proxy.d.ts +84 -0
  19. package/dist/types/run-collector.d.ts +196 -0
  20. package/dist/types/telemetry.d.ts +596 -0
  21. package/dist/types/thinking.d.ts +18 -0
  22. package/dist/types/types.d.ts +430 -0
  23. package/package.json +75 -0
  24. package/src/agent-loop.ts +1302 -0
  25. package/src/agent.ts +1531 -0
  26. package/src/append-only-context.ts +460 -0
  27. package/src/compaction/branch-summarization.ts +358 -0
  28. package/src/compaction/compaction.ts +1342 -0
  29. package/src/compaction/entries.ts +139 -0
  30. package/src/compaction/errors.ts +31 -0
  31. package/src/compaction/index.ts +12 -0
  32. package/src/compaction/messages.ts +212 -0
  33. package/src/compaction/openai.ts +570 -0
  34. package/src/compaction/prompts/auto-handoff-threshold-focus.md +1 -0
  35. package/src/compaction/prompts/branch-summary-context.md +5 -0
  36. package/src/compaction/prompts/branch-summary-preamble.md +2 -0
  37. package/src/compaction/prompts/branch-summary.md +30 -0
  38. package/src/compaction/prompts/compaction-short-summary.md +9 -0
  39. package/src/compaction/prompts/compaction-summary-context.md +5 -0
  40. package/src/compaction/prompts/compaction-summary.md +38 -0
  41. package/src/compaction/prompts/compaction-turn-prefix.md +17 -0
  42. package/src/compaction/prompts/compaction-update-summary.md +45 -0
  43. package/src/compaction/prompts/file-operations.md +10 -0
  44. package/src/compaction/prompts/handoff-document.md +49 -0
  45. package/src/compaction/prompts/summarization-system.md +3 -0
  46. package/src/compaction/pruning.ts +431 -0
  47. package/src/compaction/utils.ts +185 -0
  48. package/src/compaction.ts +1 -0
  49. package/src/harmony-leak.ts +428 -0
  50. package/src/index.ts +19 -0
  51. package/src/proxy.ts +326 -0
  52. package/src/run-collector.ts +631 -0
  53. package/src/telemetry.ts +2049 -0
  54. package/src/thinking.ts +20 -0
  55. package/src/types.ts +490 -0
@@ -0,0 +1,185 @@
1
+ /**
2
+ * Shared utilities for compaction and branch summarization.
3
+ */
4
+
5
+ import type { Message } from "@sayknow-cli/ai";
6
+ import { prompt } from "@sayknow-cli/utils";
7
+ import type { AgentMessage } from "../types";
8
+ import fileOperationsTemplate from "./prompts/file-operations.md" with { type: "text" };
9
+ import summarizationSystemPrompt from "./prompts/summarization-system.md" with { type: "text" };
10
+
11
+ // ============================================================================
12
+ // File Operation Tracking
13
+ // ============================================================================
14
+
15
+ export interface FileOperations {
16
+ read: Set<string>;
17
+ written: Set<string>;
18
+ edited: Set<string>;
19
+ }
20
+
21
+ export function createFileOps(): FileOperations {
22
+ return {
23
+ read: new Set(),
24
+ written: new Set(),
25
+ edited: new Set(),
26
+ };
27
+ }
28
+
29
+ /**
30
+ * Extract file operations from tool calls in an assistant message.
31
+ */
32
+ export function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void {
33
+ if (message.role !== "assistant") return;
34
+ if (!("content" in message) || !Array.isArray(message.content)) return;
35
+
36
+ for (const block of message.content) {
37
+ if (typeof block !== "object" || block === null) continue;
38
+ if (!("type" in block) || block.type !== "toolCall") continue;
39
+ if (!("arguments" in block) || !("name" in block)) continue;
40
+
41
+ const args = block.arguments as Record<string, unknown> | undefined;
42
+ if (!args) continue;
43
+
44
+ const path = typeof args.path === "string" ? args.path : undefined;
45
+ if (!path) continue;
46
+
47
+ switch (block.name) {
48
+ case "read":
49
+ fileOps.read.add(path);
50
+ break;
51
+ case "write":
52
+ fileOps.written.add(path);
53
+ break;
54
+ case "edit":
55
+ fileOps.edited.add(path);
56
+ break;
57
+ }
58
+ }
59
+ }
60
+
61
+ /**
62
+ * Compute final file lists from file operations.
63
+ * Returns readFiles (files only read, not modified) and modifiedFiles.
64
+ */
65
+ export function computeFileLists(fileOps: FileOperations): { readFiles: string[]; modifiedFiles: string[] } {
66
+ const modified = new Set([...fileOps.edited, ...fileOps.written]);
67
+ const readOnly = [...fileOps.read].filter(f => !modified.has(f)).sort();
68
+ const modifiedFiles = [...modified].sort();
69
+ return { readFiles: readOnly, modifiedFiles };
70
+ }
71
+
72
+ /**
73
+ * Format file operations as XML tags for summary.
74
+ */
75
+ const FILE_OPERATION_SUMMARY_LIMIT = 20;
76
+
77
+ function truncateFileList(files: string[]): string[] {
78
+ if (files.length <= FILE_OPERATION_SUMMARY_LIMIT) return files;
79
+ const omitted = files.length - FILE_OPERATION_SUMMARY_LIMIT;
80
+ return [...files.slice(0, FILE_OPERATION_SUMMARY_LIMIT), `… (${omitted} more files omitted)`];
81
+ }
82
+
83
+ function stripFileOperationTags(summary: string): string {
84
+ const withoutReadFiles = summary.replace(/<read-files>[\s\S]*?<\/read-files>\s*/g, "");
85
+ const withoutModifiedFiles = withoutReadFiles.replace(/<modified-files>[\s\S]*?<\/modified-files>\s*/g, "");
86
+ return withoutModifiedFiles.trimEnd();
87
+ }
88
+ export function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string {
89
+ if (readFiles.length === 0 && modifiedFiles.length === 0) return "";
90
+ return prompt.render(fileOperationsTemplate, {
91
+ readFiles: truncateFileList(readFiles),
92
+ modifiedFiles: truncateFileList(modifiedFiles),
93
+ });
94
+ }
95
+
96
+ export function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: string[]): string {
97
+ const baseSummary = stripFileOperationTags(summary);
98
+ const fileOperations = formatFileOperations(readFiles, modifiedFiles);
99
+ if (!fileOperations) return baseSummary;
100
+ if (!baseSummary) return fileOperations;
101
+ return `${baseSummary}\n\n${fileOperations}`;
102
+ }
103
+
104
+ // ============================================================================
105
+ // Message Serialization
106
+ // ============================================================================
107
+
108
+ /** Maximum characters for a tool result in serialized summaries. */
109
+ const TOOL_RESULT_MAX_CHARS = 2000;
110
+
111
+ /**
112
+ * Truncate text to a maximum character length for summarization.
113
+ * Keeps the beginning and appends a truncation marker.
114
+ */
115
+ function truncateForSummary(text: string, maxChars: number): string {
116
+ if (text.length <= maxChars) return text;
117
+ const truncatedChars = text.length - maxChars;
118
+ return `${text.slice(0, maxChars)}\n\n[... ${truncatedChars} more characters truncated]`;
119
+ }
120
+
121
+ /**
122
+ * Serialize LLM messages to text for summarization.
123
+ * This prevents the model from treating it as a conversation to continue.
124
+ * Call convertToLlm() first to handle custom message types.
125
+ */
126
+ export function serializeConversation(messages: Message[]): string {
127
+ const parts: string[] = [];
128
+
129
+ for (const msg of messages) {
130
+ if (msg.role === "user") {
131
+ const content =
132
+ typeof msg.content === "string"
133
+ ? msg.content
134
+ : msg.content
135
+ .filter((c): c is { type: "text"; text: string } => c.type === "text")
136
+ .map(c => c.text)
137
+ .join("");
138
+ if (content) parts.push(`[User]: ${content}`);
139
+ } else if (msg.role === "assistant") {
140
+ const textParts: string[] = [];
141
+ const thinkingParts: string[] = [];
142
+ const toolCalls: string[] = [];
143
+
144
+ for (const block of msg.content) {
145
+ if (block.type === "text") {
146
+ textParts.push(block.text);
147
+ } else if (block.type === "thinking") {
148
+ thinkingParts.push(block.thinking);
149
+ } else if (block.type === "toolCall") {
150
+ const args = block.arguments as Record<string, unknown>;
151
+ const argsStr = Object.entries(args)
152
+ .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
153
+ .join(", ");
154
+ toolCalls.push(`${block.name}(${argsStr})`);
155
+ }
156
+ }
157
+
158
+ if (thinkingParts.length > 0) {
159
+ parts.push(`[Assistant thinking]: ${thinkingParts.join("\n")}`);
160
+ }
161
+ if (textParts.length > 0) {
162
+ parts.push(`[Assistant]: ${textParts.join("\n")}`);
163
+ }
164
+ if (toolCalls.length > 0) {
165
+ parts.push(`[Assistant tool calls]: ${toolCalls.join("; ")}`);
166
+ }
167
+ } else if (msg.role === "toolResult") {
168
+ const content = msg.content
169
+ .filter((c): c is { type: "text"; text: string } => c.type === "text")
170
+ .map(c => c.text)
171
+ .join("");
172
+ if (content) {
173
+ parts.push(`[Tool result]: ${truncateForSummary(content, TOOL_RESULT_MAX_CHARS)}`);
174
+ }
175
+ }
176
+ }
177
+
178
+ return parts.join("\n\n");
179
+ }
180
+
181
+ // ============================================================================
182
+ // Summarization System Prompt
183
+ // ============================================================================
184
+
185
+ export const SUMMARIZATION_SYSTEM_PROMPT = prompt.render(summarizationSystemPrompt);
@@ -0,0 +1 @@
1
+ export * from "./compaction/index";
@@ -0,0 +1,428 @@
1
+ /**
2
+ * GPT-5 Harmony-header leakage detection and recovery.
3
+ *
4
+ * Background and policy: see `docs/ERRATA-GPT5-HARMONY.md`. This module
5
+ * implements §3 of that document: detection by signal fusion, plus a
6
+ * truncate-and-resume primitive for the `edit` tool when its input is in
7
+ * hashline DSL form. Other tools and surfaces fall through to
8
+ * abort-and-retry handled by the agent loop.
9
+ */
10
+ import type { AssistantMessage, Model, ToolCall } from "@sayknow-cli/ai";
11
+
12
+ // Single source of truth for the marker pattern. `M` in the errata.
13
+ // Use a fresh non-global instance for `.test()` to avoid lastIndex pitfalls.
14
+ const MARKER_RE = /\bto=functions\.[A-Za-z_]\w*/g;
15
+ const HARMONY_RE = /<\|(start|end|channel|message|call|return)\|>/g;
16
+
17
+ // Channel-word adjacency (`C`): channel/role name appearing immediately before the marker.
18
+ const CHANNEL_WORD_RE = /\b(?:analysis|commentary|assistant|user|system|developer|tool)\s+to=functions\./;
19
+
20
+ // Glitch-token adjacency (`G`). The Japgolly literal is escaped so this regex
21
+ // source itself does not trip detection if the file is scanned (e.g. when
22
+ // editing this module via the same agent that detects).
23
+ const GLITCH_RE = /\b(?:changedFiles|RTLU|Jsii(?:_commentary)?|\x4aapgolly)\b/;
24
+
25
+ // Body-channel cascade (`B`): marker followed by ` code` then another marker
26
+ // within 200 chars. Single regex; no manual slicing needed.
27
+ const BODY_CASCADE_RE = /to=functions\.\w+\s+code\b[\s\S]{0,200}?to=functions\./;
28
+
29
+ // Fake-result framing (`R`): marker followed within 80 chars by Cell N: framing.
30
+ const FAKE_RESULT_RE = /to=functions\.\w+[\s\S]{0,80}?code_output\s*\nCell\s+\d+:/;
31
+
32
+ const FENCE_RE = /^\s*(?:```+|~~~+)/;
33
+
34
+ // Non-Latin scripts seen in the corpus: CJK + ext, Hangul + Jamo,
35
+ // Cyrillic, Thai, Georgian, Armenian, Kannada, Telugu, Devanagari,
36
+ // Arabic, Malayalam.
37
+ const SCRIPT_CLASS =
38
+ "\u1100-\u11FF\u3130-\u318F\uA960-\uA97F\uAC00-\uD7AF\uD7B0-\uD7FF\u3400-\u4DBF\u4E00-\u9FFF\uF900-\uFAFF\u0400-\u04FF\u0E00-\u0E7F\u10A0-\u10FF\u0530-\u058F\u0C80-\u0CFF\u0C00-\u0C7F\u0900-\u097F\u0600-\u06FF\u0D00-\u0D7F";
39
+ const SCRIPT_RUN_RE = new RegExp(`[${SCRIPT_CLASS}]{2,}`, "u");
40
+
41
+ // Recovery registry. Each entry's parser must recognize the configured
42
+ // sentinel (per-tool, see eval/parse.ts and hashline/parser.ts) and surface
43
+ // a warning to the model so it knows to re-issue any remaining work.
44
+ // `accepts` gates on input shape: tools whose contaminated input doesn't
45
+ // match the parser's expected DSL fall through to abort-and-retry.
46
+ //
47
+ // • `edit`: hashline DSL input begins with `@<path>`. Apply_patch envelopes
48
+ // (`*** Begin Patch …`) and JSON-schema variants are not recoverable —
49
+ // their parsers don't recognize `*** Abort`.
50
+ // • `eval`: any string is a parseable cell sequence (the parser is lenient
51
+ // and falls back to implicit-cell mode on bare strings).
52
+ interface RecoveryConfig {
53
+ sentinel: string;
54
+ accepts: (input: string) => boolean;
55
+ }
56
+ const RECOVERY_REGISTRY: Record<string, RecoveryConfig> = {
57
+ edit: {
58
+ sentinel: "\n*** Abort\n",
59
+ accepts: input => input.replace(/^\s+/, "").startsWith("@"),
60
+ },
61
+ eval: {
62
+ sentinel: "\n*** Abort\n",
63
+ accepts: () => true,
64
+ },
65
+ };
66
+
67
+ const SIGNAL_ORDER = ["M", "C", "G", "S", "B", "R", "T"] as const;
68
+
69
+ export type HarmonySignalClass = "H" | (typeof SIGNAL_ORDER)[number];
70
+
71
+ export type HarmonySurface = "assistant_text" | "assistant_thinking" | "tool_arg";
72
+
73
+ export interface HarmonySignal {
74
+ classes: HarmonySignalClass[];
75
+ start: number;
76
+ end: number;
77
+ text: string;
78
+ }
79
+
80
+ export interface HarmonyDetection {
81
+ surface: HarmonySurface;
82
+ contentIndex?: number;
83
+ toolName?: string;
84
+ toolCallId?: string;
85
+ signals: HarmonySignal[];
86
+ }
87
+
88
+ export interface HarmonyAuditEvent {
89
+ action: "truncate_resume" | "abort_retry" | "escalated";
90
+ surface: HarmonySurface;
91
+ signal: string;
92
+ retryN: number;
93
+ model: string;
94
+ provider: string;
95
+ toolName?: string;
96
+ removedLen: number;
97
+ removedSha8: string;
98
+ removedPreview: string;
99
+ removedBlob?: string;
100
+ }
101
+
102
+ export interface HarmonyRecoveredToolCall {
103
+ message: AssistantMessage;
104
+ removed: string;
105
+ }
106
+
107
+ /**
108
+ * Whether to run leak detection on responses from this model. We default-on
109
+ * for every OpenAI code provider model rather than enumerating ids, so a future
110
+ * gpt-5.6 (or whatever) doesn't silently bypass the mitigation. Detection
111
+ * itself is cheap; the cost of missing a leak on a new model is not.
112
+ */
113
+ export function isHarmonyLeakMitigationTarget(model: Model): boolean {
114
+ return model.provider === "openai-codex";
115
+ }
116
+
117
+ export function signalListLabel(signals: readonly HarmonySignal[]): string {
118
+ const seen: string[] = [];
119
+ for (const signal of signals) {
120
+ const label = signal.classes.join("+");
121
+ if (!seen.includes(label)) seen.push(label);
122
+ }
123
+ return seen.join(",") || "none";
124
+ }
125
+
126
+ /**
127
+ * Detect harmony-protocol leakage in `text`. Returns undefined if clean.
128
+ *
129
+ * Trip rule: `H` alone, or `M` paired with at least one co-signal
130
+ * (`C`/`G`/`S`/`B`/`R`/`T`). Bare `M` does not trip — this document, its
131
+ * tests, and bug reports legitimately carry the marker.
132
+ *
133
+ * `parsedEnd`, when supplied, marks the byte at which a structurally valid
134
+ * tool-argument parse ends; markers strictly after it set the `T` co-signal.
135
+ * `contentIndex`/`toolName`/`toolCallId` flow through to the returned
136
+ * detection for downstream auditing.
137
+ */
138
+ export function detectHarmonyLeak(
139
+ text: string,
140
+ surface: HarmonySurface,
141
+ options: {
142
+ parsedEnd?: number;
143
+ contentIndex?: number;
144
+ toolName?: string;
145
+ toolCallId?: string;
146
+ } = {},
147
+ ): HarmonyDetection | undefined {
148
+ const fences = computeFenceRanges(text);
149
+ const signals: HarmonySignal[] = [];
150
+
151
+ for (const match of text.matchAll(HARMONY_RE)) {
152
+ const start = match.index ?? 0;
153
+ if (isInsideFence(fences, start)) continue;
154
+ signals.push(makeSignal(["H"], start, start + match[0].length, match[0]));
155
+ }
156
+
157
+ for (const match of text.matchAll(MARKER_RE)) {
158
+ const start = match.index ?? 0;
159
+ if (isInsideFence(fences, start)) continue;
160
+ const end = start + match[0].length;
161
+ const classes: HarmonySignalClass[] = ["M"];
162
+
163
+ const adjacent = text.slice(Math.max(0, start - 64), Math.min(text.length, end + 16));
164
+ const near = text.slice(Math.max(0, start - 16), Math.min(text.length, end + 16));
165
+ const forward = text.slice(start, Math.min(text.length, start + 240));
166
+
167
+ if (CHANNEL_WORD_RE.test(adjacent)) classes.push("C");
168
+ if (GLITCH_RE.test(near)) classes.push("G");
169
+ if (hasScriptMismatchNear(text, start, end)) classes.push("S");
170
+ if (BODY_CASCADE_RE.test(forward)) classes.push("B");
171
+ if (FAKE_RESULT_RE.test(forward)) classes.push("R");
172
+ if (options.parsedEnd !== undefined && start >= options.parsedEnd) classes.push("T");
173
+
174
+ // `M` alone never trips: legitimate documentation/tests carry it.
175
+ if (classes.length > 1) {
176
+ signals.push(makeSignal(classes, start, end, match[0]));
177
+ }
178
+ }
179
+
180
+ if (signals.length === 0) return undefined;
181
+ signals.sort((a, b) => a.start - b.start || a.end - b.end);
182
+ return {
183
+ surface,
184
+ contentIndex: options.contentIndex,
185
+ toolName: options.toolName,
186
+ toolCallId: options.toolCallId,
187
+ signals,
188
+ };
189
+ }
190
+
191
+ /** Scan an assistant message's content blocks; return the first detection. */
192
+ export function detectHarmonyLeakInAssistantMessage(message: AssistantMessage): HarmonyDetection | undefined {
193
+ for (let i = 0; i < message.content.length; i++) {
194
+ const block = message.content[i];
195
+ if (block.type === "text") {
196
+ const d = detectHarmonyLeak(block.text, "assistant_text", { contentIndex: i });
197
+ if (d) return d;
198
+ } else if (block.type === "thinking") {
199
+ const d = detectHarmonyLeak(block.thinking, "assistant_thinking", { contentIndex: i });
200
+ if (d) return d;
201
+ } else if (block.type === "toolCall") {
202
+ const argText = getToolArgumentText(block);
203
+ if (argText !== undefined) {
204
+ const d = detectHarmonyLeak(argText, "tool_arg", {
205
+ contentIndex: i,
206
+ toolName: block.name,
207
+ toolCallId: block.id,
208
+ });
209
+ if (d) return d;
210
+ }
211
+ }
212
+ }
213
+ return undefined;
214
+ }
215
+
216
+ /**
217
+ * Truncate a contaminated tool call at the start of the contaminated line and
218
+ * append the tool's recovery sentinel. Returns a recovered AssistantMessage
219
+ * (containing only the cleaned tool call), a synthetic continuation user
220
+ * message asking the model to re-issue the rest, and the removed substring
221
+ * for auditing. Returns undefined when the tool is not recovery-eligible or
222
+ * the truncation would leave nothing meaningful to dispatch.
223
+ *
224
+ * `providerPayload` is dropped from the recovered message: for OpenAI code backend the
225
+ * encrypted reasoning blob is opaque/signed and we cannot validate that it is
226
+ * uncontaminated. The model re-reasons on the next turn.
227
+ */
228
+ export function recoverHarmonyToolCall(
229
+ message: AssistantMessage,
230
+ detection: HarmonyDetection,
231
+ ): HarmonyRecoveredToolCall | undefined {
232
+ if (detection.surface !== "tool_arg" || detection.contentIndex === undefined) return undefined;
233
+ const block = message.content[detection.contentIndex];
234
+ if (block?.type !== "toolCall") return undefined;
235
+
236
+ const config = RECOVERY_REGISTRY[block.name];
237
+ if (!config) return undefined;
238
+
239
+ const input = block.arguments?.input;
240
+ if (typeof input !== "string") return undefined;
241
+ if (!config.accepts(input)) return undefined;
242
+
243
+ const offset = detection.signals[0]?.start;
244
+ if (offset === undefined) return undefined;
245
+
246
+ const truncated = truncateAtLineAndAppendSentinel(input, offset, config.sentinel);
247
+ if (truncated === undefined) return undefined;
248
+
249
+ const cleanToolCall: ToolCall = {
250
+ ...block,
251
+ arguments: { ...block.arguments, input: truncated.clean },
252
+ };
253
+ const cleanMessage: AssistantMessage = {
254
+ ...message,
255
+ content: [cleanToolCall],
256
+ // Drop encrypted reasoning blob: opaque, possibly carries the leak forward.
257
+ providerPayload: undefined,
258
+ stopReason: "toolUse",
259
+ errorMessage: undefined,
260
+ };
261
+ return { message: cleanMessage, removed: truncated.removed };
262
+ }
263
+
264
+ /**
265
+ * Return the contaminated substring from `message` for audit purposes when
266
+ * recovery is not applicable (abort path). Walks from the first detected
267
+ * signal to end-of-content within the relevant block. Returns "" if the
268
+ * detection cannot be resolved against the message.
269
+ */
270
+ export function extractHarmonyRemoved(message: AssistantMessage, detection: HarmonyDetection): string {
271
+ if (detection.contentIndex === undefined) return "";
272
+ const block = message.content[detection.contentIndex];
273
+ if (!block) return "";
274
+ const start = detection.signals[0]?.start ?? 0;
275
+ if (block.type === "text") return block.text.slice(start);
276
+ if (block.type === "thinking") return block.thinking.slice(start);
277
+ if (block.type === "toolCall") {
278
+ const text = getToolArgumentText(block);
279
+ return text ? text.slice(start) : "";
280
+ }
281
+ return "";
282
+ }
283
+
284
+ export function createHarmonyAuditEvent(params: {
285
+ action: HarmonyAuditEvent["action"];
286
+ detection: HarmonyDetection;
287
+ model: Model;
288
+ retryN: number;
289
+ removed: string;
290
+ }): HarmonyAuditEvent {
291
+ return {
292
+ action: params.action,
293
+ surface: params.detection.surface,
294
+ signal: signalListLabel(params.detection.signals),
295
+ retryN: params.retryN,
296
+ model: params.model.id,
297
+ provider: params.model.provider,
298
+ toolName: params.detection.toolName,
299
+ removedLen: params.removed.length,
300
+ removedSha8: sha8(params.removed),
301
+ removedPreview: redactedJunkPreview(params.removed),
302
+ removedBlob: Bun.env.SKC_HARMONY_DEBUG === "1" ? params.removed : undefined,
303
+ };
304
+ }
305
+
306
+ // ─── internals ──────────────────────────────────────────────────────────────
307
+
308
+ function makeSignal(classes: HarmonySignalClass[], start: number, end: number, text: string): HarmonySignal {
309
+ if (classes[0] === "H") return { classes: ["H"], start, end, text };
310
+ const sorted: HarmonySignalClass[] = [];
311
+ for (const cls of SIGNAL_ORDER) {
312
+ if (classes.includes(cls)) sorted.push(cls);
313
+ }
314
+ return { classes: sorted, start, end, text };
315
+ }
316
+
317
+ /**
318
+ * Precompute fenced-code-block ranges once per text. Each range is a
319
+ * [start, end) span of bytes inside any ```/~~~ fence. O(n) once instead of
320
+ * O(n) per detected match.
321
+ */
322
+ function computeFenceRanges(text: string): Array<[number, number]> {
323
+ const ranges: Array<[number, number]> = [];
324
+ let inFence = false;
325
+ let fenceStart = 0;
326
+ let lineStart = 0;
327
+ while (lineStart <= text.length) {
328
+ const newline = text.indexOf("\n", lineStart);
329
+ const lineEnd = newline === -1 ? text.length : newline;
330
+ const line = text.slice(lineStart, lineEnd);
331
+ if (FENCE_RE.test(line)) {
332
+ if (inFence) {
333
+ ranges.push([fenceStart, lineEnd]);
334
+ inFence = false;
335
+ } else {
336
+ fenceStart = lineStart;
337
+ inFence = true;
338
+ }
339
+ }
340
+ if (newline === -1) break;
341
+ lineStart = newline + 1;
342
+ }
343
+ if (inFence) ranges.push([fenceStart, text.length]);
344
+ return ranges;
345
+ }
346
+
347
+ function isInsideFence(ranges: Array<[number, number]>, position: number): boolean {
348
+ for (const [start, end] of ranges) {
349
+ if (position >= start && position < end) return true;
350
+ if (start > position) break;
351
+ }
352
+ return false;
353
+ }
354
+
355
+ function hasScriptMismatchNear(text: string, start: number, end: number): boolean {
356
+ const near = text.slice(Math.max(0, start - 32), Math.min(text.length, end + 32));
357
+ if (!SCRIPT_RUN_RE.test(near)) return false;
358
+ const surrounding = text.slice(Math.max(0, start - 200), Math.min(text.length, end + 200));
359
+ if (surrounding.length === 0) return false;
360
+ let ascii = 0;
361
+ for (let i = 0; i < surrounding.length; i++) {
362
+ if (surrounding.charCodeAt(i) < 128) ascii++;
363
+ }
364
+ return ascii / surrounding.length >= 0.85;
365
+ }
366
+
367
+ /**
368
+ * Tool-call argument text used for detection scanning. For tools whose args
369
+ * include a free-form `input` string we scan that directly so reported byte
370
+ * offsets line up with the original. For everything else we fall back to a
371
+ * JSON-stringified blob so detection still fires; that path's offsets are
372
+ * NOT meaningful for slicing the original args, but the recovery path gates
373
+ * on `block.arguments.input` being a string and only ever slices that.
374
+ */
375
+ function getToolArgumentText(toolCall: ToolCall): string | undefined {
376
+ if (typeof toolCall.arguments?.input === "string") return toolCall.arguments.input;
377
+ try {
378
+ return JSON.stringify(toolCall.arguments);
379
+ } catch {
380
+ return undefined;
381
+ }
382
+ }
383
+
384
+ function truncateAtLineAndAppendSentinel(
385
+ input: string,
386
+ offset: number,
387
+ sentinel: string,
388
+ ): { clean: string; removed: string } | undefined {
389
+ const lineStart = offset <= 0 ? 0 : input.lastIndexOf("\n", offset - 1) + 1;
390
+ if (lineStart === 0) return undefined; // would cut everything
391
+ const head = input.slice(0, lineStart).replace(/\s+$/, "");
392
+ if (head.length === 0) return undefined;
393
+ return {
394
+ clean: head + sentinel,
395
+ removed: input.slice(lineStart),
396
+ };
397
+ }
398
+
399
+ function sha8(text: string): string {
400
+ return Bun.sha(text, "hex").slice(0, 8);
401
+ }
402
+
403
+ const PREVIEW_KEEP_RE = new RegExp(`[${SCRIPT_CLASS}\\s】【”“…」「、。]`, "u");
404
+ const PREVIEW_TOKEN_RE =
405
+ /^(?:to=functions\.[A-Za-z_]\w*|analysis|commentary|assistant|user|system|developer|tool|changedFiles|RTLU|Jsii(?:_commentary)?|\x4aapgolly)/;
406
+
407
+ /**
408
+ * Privacy-safe preview for the audit log: keeps marker/channel/glitch tokens,
409
+ * non-Latin script chars, and CJK punctuation; replaces everything else
410
+ * (potential source/secrets) with `·`. Sufficient to grow the glitch-token
411
+ * denylist from logs without exposing source content. Capped at 64 chars.
412
+ */
413
+ function redactedJunkPreview(text: string): string {
414
+ const source = text.slice(0, 64);
415
+ let out = "";
416
+ for (let i = 0; i < source.length; ) {
417
+ const tok = PREVIEW_TOKEN_RE.exec(source.slice(i));
418
+ if (tok) {
419
+ out += tok[0];
420
+ i += tok[0].length;
421
+ continue;
422
+ }
423
+ const ch = source[i] ?? "";
424
+ out += PREVIEW_KEEP_RE.test(ch) ? ch : "·";
425
+ i++;
426
+ }
427
+ return out;
428
+ }
package/src/index.ts ADDED
@@ -0,0 +1,19 @@
1
+ // Core Agent
2
+ export * from "./agent";
3
+ // Loop functions
4
+ export * from "./agent-loop";
5
+ // Append-only context mode
6
+ export * from "./append-only-context";
7
+ // Compaction
8
+ export * from "./compaction";
9
+ export * from "./harmony-leak";
10
+ // Proxy utilities
11
+ export * from "./proxy";
12
+ // Run-level telemetry collector + aggregators
13
+ export * from "./run-collector";
14
+ // Telemetry
15
+ export * from "./telemetry";
16
+ // Thinking selectors
17
+ export * from "./thinking";
18
+ // Types
19
+ export * from "./types";