@archmax-ai/harness 0.0.0

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 (351) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +219 -0
  3. package/dist/agent.d.ts +174 -0
  4. package/dist/agent.js +140 -0
  5. package/dist/agent.js.map +1 -0
  6. package/dist/assembly/compose.d.ts +170 -0
  7. package/dist/assembly/compose.js +391 -0
  8. package/dist/assembly/compose.js.map +1 -0
  9. package/dist/assembly/delegation-registry.d.ts +5 -0
  10. package/dist/assembly/delegation-registry.js +118 -0
  11. package/dist/assembly/delegation-registry.js.map +1 -0
  12. package/dist/assembly/index.d.ts +192 -0
  13. package/dist/assembly/index.js +265 -0
  14. package/dist/assembly/index.js.map +1 -0
  15. package/dist/assembly/plain.d.ts +7 -0
  16. package/dist/assembly/plain.js +41 -0
  17. package/dist/assembly/plain.js.map +1 -0
  18. package/dist/authoring-skill/archmax-harness/README.md +76 -0
  19. package/dist/authoring-skill/archmax-harness/SKILL.md +241 -0
  20. package/dist/authoring-skill/archmax-harness/references/backend-integration.md +626 -0
  21. package/dist/authoring-skill/archmax-harness/references/cases.md +41 -0
  22. package/dist/authoring-skill/archmax-harness/references/diagnostics.md +51 -0
  23. package/dist/authoring-skill/archmax-harness/references/hook-and-test-scripts.md +1070 -0
  24. package/dist/authoring-skill/archmax-harness/references/hooks-and-scripts.md +82 -0
  25. package/dist/authoring-skill/archmax-harness/references/wiring.md +101 -0
  26. package/dist/authoring-skill/archmax-harness/references/workflow-schema.md +1631 -0
  27. package/dist/authoring-skill/archmax-harness/references/workflow-yaml.md +241 -0
  28. package/dist/behaviour/support.d.ts +232 -0
  29. package/dist/behaviour/support.js +339 -0
  30. package/dist/behaviour/support.js.map +1 -0
  31. package/dist/cli/banner.d.ts +11 -0
  32. package/dist/cli/banner.js +29 -0
  33. package/dist/cli/banner.js.map +1 -0
  34. package/dist/cli/bootstrap.d.ts +33 -0
  35. package/dist/cli/bootstrap.js +153 -0
  36. package/dist/cli/bootstrap.js.map +1 -0
  37. package/dist/cli/command.d.ts +39 -0
  38. package/dist/cli/command.js +97 -0
  39. package/dist/cli/command.js.map +1 -0
  40. package/dist/cli/state-flow.d.ts +46 -0
  41. package/dist/cli/state-flow.js +268 -0
  42. package/dist/cli/state-flow.js.map +1 -0
  43. package/dist/cli/style.d.ts +41 -0
  44. package/dist/cli/style.js +64 -0
  45. package/dist/cli/style.js.map +1 -0
  46. package/dist/cli/turn.d.ts +41 -0
  47. package/dist/cli/turn.js +161 -0
  48. package/dist/cli/turn.js.map +1 -0
  49. package/dist/cli.d.ts +10 -0
  50. package/dist/cli.js +426 -0
  51. package/dist/cli.js.map +1 -0
  52. package/dist/core/code-description.d.ts +22 -0
  53. package/dist/core/code-description.js +38 -0
  54. package/dist/core/code-description.js.map +1 -0
  55. package/dist/core/deepagents.d.ts +183 -0
  56. package/dist/core/deepagents.js +128 -0
  57. package/dist/core/deepagents.js.map +1 -0
  58. package/dist/core/events.d.ts +350 -0
  59. package/dist/core/events.js +205 -0
  60. package/dist/core/events.js.map +1 -0
  61. package/dist/core/frontmatter.d.ts +15 -0
  62. package/dist/core/frontmatter.js +32 -0
  63. package/dist/core/frontmatter.js.map +1 -0
  64. package/dist/core/listing-redact.d.ts +37 -0
  65. package/dist/core/listing-redact.js +88 -0
  66. package/dist/core/listing-redact.js.map +1 -0
  67. package/dist/core/match.d.ts +26 -0
  68. package/dist/core/match.js +75 -0
  69. package/dist/core/match.js.map +1 -0
  70. package/dist/core/message-readers.d.ts +84 -0
  71. package/dist/core/message-readers.js +159 -0
  72. package/dist/core/message-readers.js.map +1 -0
  73. package/dist/core/messages.d.ts +49 -0
  74. package/dist/core/messages.js +85 -0
  75. package/dist/core/messages.js.map +1 -0
  76. package/dist/core/mount-prompt.d.ts +28 -0
  77. package/dist/core/mount-prompt.js +55 -0
  78. package/dist/core/mount-prompt.js.map +1 -0
  79. package/dist/core/mount-redact.d.ts +28 -0
  80. package/dist/core/mount-redact.js +32 -0
  81. package/dist/core/mount-redact.js.map +1 -0
  82. package/dist/core/mounts.d.ts +88 -0
  83. package/dist/core/mounts.js +147 -0
  84. package/dist/core/mounts.js.map +1 -0
  85. package/dist/core/path-mapping.d.ts +52 -0
  86. package/dist/core/path-mapping.js +113 -0
  87. package/dist/core/path-mapping.js.map +1 -0
  88. package/dist/core/platform-prompt.generated.d.ts +2 -0
  89. package/dist/core/platform-prompt.generated.js +4 -0
  90. package/dist/core/platform-prompt.generated.js.map +1 -0
  91. package/dist/core/prompt.d.ts +42 -0
  92. package/dist/core/prompt.js +75 -0
  93. package/dist/core/prompt.js.map +1 -0
  94. package/dist/core/session-id.d.ts +38 -0
  95. package/dist/core/session-id.js +61 -0
  96. package/dist/core/session-id.js.map +1 -0
  97. package/dist/core/session-store.d.ts +85 -0
  98. package/dist/core/session-store.js +149 -0
  99. package/dist/core/session-store.js.map +1 -0
  100. package/dist/core/session-zone.d.ts +54 -0
  101. package/dist/core/session-zone.js +82 -0
  102. package/dist/core/session-zone.js.map +1 -0
  103. package/dist/core/skill-prompt.d.ts +31 -0
  104. package/dist/core/skill-prompt.js +54 -0
  105. package/dist/core/skill-prompt.js.map +1 -0
  106. package/dist/core/skill-redact.d.ts +15 -0
  107. package/dist/core/skill-redact.js +27 -0
  108. package/dist/core/skill-redact.js.map +1 -0
  109. package/dist/core/skills.d.ts +172 -0
  110. package/dist/core/skills.js +214 -0
  111. package/dist/core/skills.js.map +1 -0
  112. package/dist/core/tool-mocks.d.ts +23 -0
  113. package/dist/core/tool-mocks.js +39 -0
  114. package/dist/core/tool-mocks.js.map +1 -0
  115. package/dist/core/tool-telemetry.d.ts +16 -0
  116. package/dist/core/tool-telemetry.js +40 -0
  117. package/dist/core/tool-telemetry.js.map +1 -0
  118. package/dist/core/usage.d.ts +114 -0
  119. package/dist/core/usage.js +226 -0
  120. package/dist/core/usage.js.map +1 -0
  121. package/dist/core/workspace-context.d.ts +136 -0
  122. package/dist/core/workspace-context.js +178 -0
  123. package/dist/core/workspace-context.js.map +1 -0
  124. package/dist/core/workspace-prompt.d.ts +7 -0
  125. package/dist/core/workspace-prompt.js +102 -0
  126. package/dist/core/workspace-prompt.js.map +1 -0
  127. package/dist/core/workspace-router.d.ts +61 -0
  128. package/dist/core/workspace-router.js +145 -0
  129. package/dist/core/workspace-router.js.map +1 -0
  130. package/dist/core/workspace.d.ts +85 -0
  131. package/dist/core/workspace.js +193 -0
  132. package/dist/core/workspace.js.map +1 -0
  133. package/dist/core/zones.d.ts +181 -0
  134. package/dist/core/zones.js +202 -0
  135. package/dist/core/zones.js.map +1 -0
  136. package/dist/env.d.ts +99 -0
  137. package/dist/env.js +271 -0
  138. package/dist/env.js.map +1 -0
  139. package/dist/index.d.ts +265 -0
  140. package/dist/index.js +197 -0
  141. package/dist/index.js.map +1 -0
  142. package/dist/kernel/kernel.d.ts +192 -0
  143. package/dist/kernel/kernel.js +751 -0
  144. package/dist/kernel/kernel.js.map +1 -0
  145. package/dist/lifecycle/hook-shape.d.ts +44 -0
  146. package/dist/lifecycle/hook-shape.js +66 -0
  147. package/dist/lifecycle/hook-shape.js.map +1 -0
  148. package/dist/lifecycle/runner.d.ts +177 -0
  149. package/dist/lifecycle/runner.js +372 -0
  150. package/dist/lifecycle/runner.js.map +1 -0
  151. package/dist/lifecycle/transcript.d.ts +27 -0
  152. package/dist/lifecycle/transcript.js +43 -0
  153. package/dist/lifecycle/transcript.js.map +1 -0
  154. package/dist/machine/allow.d.ts +65 -0
  155. package/dist/machine/allow.js +107 -0
  156. package/dist/machine/allow.js.map +1 -0
  157. package/dist/machine/delegation.d.ts +9 -0
  158. package/dist/machine/delegation.js +10 -0
  159. package/dist/machine/delegation.js.map +1 -0
  160. package/dist/machine/diagnostic.d.ts +14 -0
  161. package/dist/machine/diagnostic.js +2 -0
  162. package/dist/machine/diagnostic.js.map +1 -0
  163. package/dist/machine/lint-spec.d.ts +4 -0
  164. package/dist/machine/lint-spec.js +266 -0
  165. package/dist/machine/lint-spec.js.map +1 -0
  166. package/dist/machine/load-spec.d.ts +90 -0
  167. package/dist/machine/load-spec.js +120 -0
  168. package/dist/machine/load-spec.js.map +1 -0
  169. package/dist/machine/machine.d.ts +273 -0
  170. package/dist/machine/machine.js +551 -0
  171. package/dist/machine/machine.js.map +1 -0
  172. package/dist/machine/mount-grants.d.ts +25 -0
  173. package/dist/machine/mount-grants.js +24 -0
  174. package/dist/machine/mount-grants.js.map +1 -0
  175. package/dist/machine/slug.d.ts +14 -0
  176. package/dist/machine/slug.js +17 -0
  177. package/dist/machine/slug.js.map +1 -0
  178. package/dist/machine/spec-schema.d.ts +662 -0
  179. package/dist/machine/spec-schema.js +717 -0
  180. package/dist/machine/spec-schema.js.map +1 -0
  181. package/dist/machine/tool-names.d.ts +98 -0
  182. package/dist/machine/tool-names.js +144 -0
  183. package/dist/machine/tool-names.js.map +1 -0
  184. package/dist/machine/triggers.d.ts +114 -0
  185. package/dist/machine/triggers.js +165 -0
  186. package/dist/machine/triggers.js.map +1 -0
  187. package/dist/machine/types.d.ts +186 -0
  188. package/dist/machine/types.js +12 -0
  189. package/dist/machine/types.js.map +1 -0
  190. package/dist/machine/validate-spec.d.ts +42 -0
  191. package/dist/machine/validate-spec.js +29 -0
  192. package/dist/machine/validate-spec.js.map +1 -0
  193. package/dist/machine/variables.d.ts +196 -0
  194. package/dist/machine/variables.js +415 -0
  195. package/dist/machine/variables.js.map +1 -0
  196. package/dist/public/cli.d.ts +15 -0
  197. package/dist/public/cli.js +14 -0
  198. package/dist/public/cli.js.map +1 -0
  199. package/dist/public/messages.d.ts +33 -0
  200. package/dist/public/messages.js +33 -0
  201. package/dist/public/messages.js.map +1 -0
  202. package/dist/public/sandbox.d.ts +99 -0
  203. package/dist/public/sandbox.js +32 -0
  204. package/dist/public/sandbox.js.map +1 -0
  205. package/dist/public/spec.d.ts +147 -0
  206. package/dist/public/spec.js +149 -0
  207. package/dist/public/spec.js.map +1 -0
  208. package/dist/public/testing.d.ts +71 -0
  209. package/dist/public/testing.js +39 -0
  210. package/dist/public/testing.js.map +1 -0
  211. package/dist/rubrics/rubrics.d.ts +135 -0
  212. package/dist/rubrics/rubrics.js +145 -0
  213. package/dist/rubrics/rubrics.js.map +1 -0
  214. package/dist/runtime/contract.d.ts +73 -0
  215. package/dist/runtime/contract.js +96 -0
  216. package/dist/runtime/contract.js.map +1 -0
  217. package/dist/sandbox/assets/parts/core.js +22 -0
  218. package/dist/sandbox/assets/parts/lifecycle-hook.js +47 -0
  219. package/dist/sandbox/bridge.d.ts +16 -0
  220. package/dist/sandbox/bridge.js +95 -0
  221. package/dist/sandbox/bridge.js.map +1 -0
  222. package/dist/sandbox/executor.d.ts +46 -0
  223. package/dist/sandbox/executor.js +119 -0
  224. package/dist/sandbox/executor.js.map +1 -0
  225. package/dist/sandbox/imports.d.ts +33 -0
  226. package/dist/sandbox/imports.js +67 -0
  227. package/dist/sandbox/imports.js.map +1 -0
  228. package/dist/sandbox/prelude.d.ts +12 -0
  229. package/dist/sandbox/prelude.js +51 -0
  230. package/dist/sandbox/prelude.js.map +1 -0
  231. package/dist/sandbox/ptc-gateway.d.ts +104 -0
  232. package/dist/sandbox/ptc-gateway.js +167 -0
  233. package/dist/sandbox/ptc-gateway.js.map +1 -0
  234. package/dist/sandbox/runtime.d.ts +59 -0
  235. package/dist/sandbox/runtime.js +51 -0
  236. package/dist/sandbox/runtime.js.map +1 -0
  237. package/dist/sandbox/tools.d.ts +34 -0
  238. package/dist/sandbox/tools.js +147 -0
  239. package/dist/sandbox/tools.js.map +1 -0
  240. package/dist/sessions/operations.d.ts +79 -0
  241. package/dist/sessions/operations.js +121 -0
  242. package/dist/sessions/operations.js.map +1 -0
  243. package/dist/sessions/resolve.d.ts +97 -0
  244. package/dist/sessions/resolve.js +145 -0
  245. package/dist/sessions/resolve.js.map +1 -0
  246. package/dist/sessions/resume.d.ts +242 -0
  247. package/dist/sessions/resume.js +288 -0
  248. package/dist/sessions/resume.js.map +1 -0
  249. package/dist/sessions/scope.d.ts +99 -0
  250. package/dist/sessions/scope.js +145 -0
  251. package/dist/sessions/scope.js.map +1 -0
  252. package/dist/sessions/summary.d.ts +65 -0
  253. package/dist/sessions/summary.js +56 -0
  254. package/dist/sessions/summary.js.map +1 -0
  255. package/dist/testing/assertions.d.ts +30 -0
  256. package/dist/testing/assertions.js +231 -0
  257. package/dist/testing/assertions.js.map +1 -0
  258. package/dist/testing/case-document.d.ts +141 -0
  259. package/dist/testing/case-document.js +51 -0
  260. package/dist/testing/case-document.js.map +1 -0
  261. package/dist/testing/case-schema.d.ts +29 -0
  262. package/dist/testing/case-schema.js +519 -0
  263. package/dist/testing/case-schema.js.map +1 -0
  264. package/dist/testing/discovery.d.ts +10 -0
  265. package/dist/testing/discovery.js +24 -0
  266. package/dist/testing/discovery.js.map +1 -0
  267. package/dist/testing/driver.d.ts +78 -0
  268. package/dist/testing/driver.js +117 -0
  269. package/dist/testing/driver.js.map +1 -0
  270. package/dist/testing/grade.d.ts +116 -0
  271. package/dist/testing/grade.js +261 -0
  272. package/dist/testing/grade.js.map +1 -0
  273. package/dist/testing/interpreter.d.ts +55 -0
  274. package/dist/testing/interpreter.js +103 -0
  275. package/dist/testing/interpreter.js.map +1 -0
  276. package/dist/testing/mock-middleware.d.ts +5 -0
  277. package/dist/testing/mock-middleware.js +33 -0
  278. package/dist/testing/mock-middleware.js.map +1 -0
  279. package/dist/testing/runner.d.ts +205 -0
  280. package/dist/testing/runner.js +266 -0
  281. package/dist/testing/runner.js.map +1 -0
  282. package/dist/testing/target.d.ts +27 -0
  283. package/dist/testing/target.js +21 -0
  284. package/dist/testing/target.js.map +1 -0
  285. package/dist/validate/validate.d.ts +41 -0
  286. package/dist/validate/validate.js +669 -0
  287. package/dist/validate/validate.js.map +1 -0
  288. package/dist/workflow/agent-tools.d.ts +10 -0
  289. package/dist/workflow/agent-tools.js +10 -0
  290. package/dist/workflow/agent-tools.js.map +1 -0
  291. package/dist/workflow/checkpointer.d.ts +52 -0
  292. package/dist/workflow/checkpointer.js +200 -0
  293. package/dist/workflow/checkpointer.js.map +1 -0
  294. package/dist/workflow/control-tools.d.ts +174 -0
  295. package/dist/workflow/control-tools.js +468 -0
  296. package/dist/workflow/control-tools.js.map +1 -0
  297. package/dist/workflow/governance.d.ts +104 -0
  298. package/dist/workflow/governance.js +546 -0
  299. package/dist/workflow/governance.js.map +1 -0
  300. package/dist/workflow/middleware.d.ts +85 -0
  301. package/dist/workflow/middleware.js +283 -0
  302. package/dist/workflow/middleware.js.map +1 -0
  303. package/dist/workflow/on-error.d.ts +25 -0
  304. package/dist/workflow/on-error.js +58 -0
  305. package/dist/workflow/on-error.js.map +1 -0
  306. package/dist/workflow/parks.d.ts +46 -0
  307. package/dist/workflow/parks.js +513 -0
  308. package/dist/workflow/parks.js.map +1 -0
  309. package/dist/workflow/paths.d.ts +67 -0
  310. package/dist/workflow/paths.js +108 -0
  311. package/dist/workflow/paths.js.map +1 -0
  312. package/dist/workflow/prompt-cache.d.ts +70 -0
  313. package/dist/workflow/prompt-cache.js +103 -0
  314. package/dist/workflow/prompt-cache.js.map +1 -0
  315. package/dist/workflow/prompt-pruning.d.ts +20 -0
  316. package/dist/workflow/prompt-pruning.js +83 -0
  317. package/dist/workflow/prompt-pruning.js.map +1 -0
  318. package/dist/workflow/render-prompt.d.ts +45 -0
  319. package/dist/workflow/render-prompt.js +140 -0
  320. package/dist/workflow/render-prompt.js.map +1 -0
  321. package/dist/workflow/runtime-config.d.ts +7 -0
  322. package/dist/workflow/runtime-config.js +9 -0
  323. package/dist/workflow/runtime-config.js.map +1 -0
  324. package/dist/workflow/session-artifacts.d.ts +90 -0
  325. package/dist/workflow/session-artifacts.js +134 -0
  326. package/dist/workflow/session-artifacts.js.map +1 -0
  327. package/dist/workflow/session-view.d.ts +31 -0
  328. package/dist/workflow/session-view.js +94 -0
  329. package/dist/workflow/session-view.js.map +1 -0
  330. package/dist/workflow/snapshot.d.ts +14 -0
  331. package/dist/workflow/snapshot.js +97 -0
  332. package/dist/workflow/snapshot.js.map +1 -0
  333. package/dist/workflow/state.d.ts +347 -0
  334. package/dist/workflow/state.js +322 -0
  335. package/dist/workflow/state.js.map +1 -0
  336. package/dist/workflow/sub-workflow.d.ts +174 -0
  337. package/dist/workflow/sub-workflow.js +392 -0
  338. package/dist/workflow/sub-workflow.js.map +1 -0
  339. package/dist/workflow/tool-service.d.ts +48 -0
  340. package/dist/workflow/tool-service.js +291 -0
  341. package/dist/workflow/tool-service.js.map +1 -0
  342. package/dist/workflow/turn-boundary.d.ts +39 -0
  343. package/dist/workflow/turn-boundary.js +128 -0
  344. package/dist/workflow/turn-boundary.js.map +1 -0
  345. package/dist/workflow/turn-runner.d.ts +40 -0
  346. package/dist/workflow/turn-runner.js +122 -0
  347. package/dist/workflow/turn-runner.js.map +1 -0
  348. package/dist/workflow/workflow-tools.d.ts +46 -0
  349. package/dist/workflow/workflow-tools.js +90 -0
  350. package/dist/workflow/workflow-tools.js.map +1 -0
  351. package/package.json +119 -0
@@ -0,0 +1,90 @@
1
+ import { type WorkflowEventHandler } from "../core/events.js";
2
+ import type { Workspace } from "../core/workspace.js";
3
+ import type { WorkflowMachine } from "../machine/machine.js";
4
+ import type { VariableStore } from "../machine/variables.js";
5
+ import type { ResolvedRuntimeContract } from "../runtime/contract.js";
6
+ import type { UsageSummary } from "../core/usage.js";
7
+ import type { TrailStep } from "./state.js";
8
+ export type { IntrospectableGraph } from "../core/deepagents.js";
9
+ import type { IntrospectableGraph } from "../core/deepagents.js";
10
+ /** Machine-readable snapshot of a run's topology (`graph.json`). */
11
+ export interface SerializedGraph {
12
+ nodes: string[];
13
+ edges: {
14
+ source: string;
15
+ target: string;
16
+ conditional: boolean;
17
+ label?: string;
18
+ }[];
19
+ entry?: string;
20
+ finals: string[];
21
+ mermaid: string;
22
+ }
23
+ export interface MessageItem {
24
+ kind: "message";
25
+ role: string;
26
+ content: string;
27
+ }
28
+ export interface ToolCallItem {
29
+ kind: "tool_call";
30
+ name: string;
31
+ args: unknown;
32
+ /** Tool result text, or null if it was not observed within this stretch. */
33
+ result: string | null;
34
+ }
35
+ export type TrajectoryItem = MessageItem | ToolCallItem;
36
+ /** One state's stretch of a turn, with the activity produced while active. */
37
+ export interface TrajectorySegment {
38
+ node: string;
39
+ enteredState?: string;
40
+ exitedState?: string;
41
+ items: TrajectoryItem[];
42
+ }
43
+ /** Ordered, state-grouped record of everything the agent did during a session. */
44
+ export interface Trajectory {
45
+ sessionId?: string;
46
+ /** @deprecated Older spelling of {@link sessionId}; kept for one release. */
47
+ runId?: string;
48
+ workflow: string;
49
+ prompt?: string;
50
+ finalAnswer: string;
51
+ segments: TrajectorySegment[];
52
+ }
53
+ /** Session metadata recorded so a historical session stays interpretable after the SDK evolves. */
54
+ export interface RunMetadata {
55
+ runtimeContract: ResolvedRuntimeContract;
56
+ packageVersion: string;
57
+ /** The `specHash` that governed this run, resolvable via `readSpecSnapshot`. Absent for a plain agent. */
58
+ specHash?: string;
59
+ /** Token accounting, plus `costUsd` when the model is priced. Absent when no usage was reported. */
60
+ usage?: UsageSummary;
61
+ }
62
+ /** Serialize a compiled LangGraph runnable's topology — the plain agent's graph, which has no machine. */
63
+ export declare function serializeGraph(graph: IntrospectableGraph): Promise<SerializedGraph>;
64
+ /**
65
+ * Serialize the machine's own topology: states, declared transitions (labelled
66
+ * with their descriptions), each `on_error` route as a conditional edge, and one
67
+ * start edge per declared trigger. Derived from the spec, never from a compiled
68
+ * graph, so it cannot disagree with what was enforced.
69
+ */
70
+ export declare function serializeMachineGraph(machine: WorkflowMachine): SerializedGraph;
71
+ /** The machine's topology as one log line per state, for the `graph-topology` diagnostic. */
72
+ export declare function describeMachineTopology(machine: WorkflowMachine): string;
73
+ /** One variable as recorded in `variables.json`. */
74
+ export interface RecordedVariable {
75
+ value: unknown;
76
+ locked: boolean;
77
+ }
78
+ /**
79
+ * Persist the session's graph, trajectory, audit trail and variables under
80
+ * `<sessionId>/artifacts/`. An absent trail means "unreadable", an empty one "no
81
+ * transitions"; an empty variable store is still written for the same reason.
82
+ * Best-effort: a write failure is a `warning` event and `null`.
83
+ */
84
+ export declare function writeRunArtifacts(workspace: Workspace, workflow: string, sessionId: string, artifacts: {
85
+ graph: SerializedGraph;
86
+ trajectory: Trajectory;
87
+ metadata?: RunMetadata;
88
+ trail?: TrailStep[];
89
+ variables?: VariableStore;
90
+ }, onEvent?: WorkflowEventHandler): Promise<string | null>;
@@ -0,0 +1,134 @@
1
+ import { createWorkflowEventEmitter } from "../core/events.js";
2
+ import { runArtifactPaths } from "./paths.js";
3
+ const START_IDS = new Set(["__start__", "START"]);
4
+ const END_IDS = new Set(["__end__", "END"]);
5
+ /** Serialize a compiled LangGraph runnable's topology — the plain agent's graph, which has no machine. */
6
+ export async function serializeGraph(graph) {
7
+ const g = await graph.getGraphAsync({});
8
+ const nodes = Object.values(g.nodes).map((n) => n.id);
9
+ const edges = g.edges.map((e) => ({
10
+ source: e.source,
11
+ target: e.target,
12
+ conditional: e.conditional === true,
13
+ ...(e.data ? { label: e.data } : {}),
14
+ }));
15
+ const entry = edges.find((e) => START_IDS.has(e.source))?.target;
16
+ const finals = edges.filter((e) => END_IDS.has(e.target)).map((e) => e.source);
17
+ return { nodes, edges, entry, finals, mermaid: g.drawMermaid() };
18
+ }
19
+ function mermaidId(slug) {
20
+ return slug.replace(/[^A-Za-z0-9_]/g, "_");
21
+ }
22
+ /**
23
+ * Serialize the machine's own topology: states, declared transitions (labelled
24
+ * with their descriptions), each `on_error` route as a conditional edge, and one
25
+ * start edge per declared trigger. Derived from the spec, never from a compiled
26
+ * graph, so it cannot disagree with what was enforced.
27
+ */
28
+ export function serializeMachineGraph(machine) {
29
+ const states = Object.keys(machine.spec.states);
30
+ const edges = [];
31
+ for (const { trigger, state } of machine.startStates()) {
32
+ edges.push({ source: "__start__", target: state, conditional: true, label: trigger });
33
+ }
34
+ for (const slug of states) {
35
+ for (const transition of machine.spec.states[slug]?.transitions ?? []) {
36
+ edges.push({
37
+ source: slug,
38
+ target: transition.to,
39
+ conditional: false,
40
+ ...(transition.description ? { label: transition.description } : {}),
41
+ });
42
+ }
43
+ const errorTarget = machine.onError(slug);
44
+ if (errorTarget)
45
+ edges.push({ source: slug, target: errorTarget, conditional: true, label: "on_error" });
46
+ }
47
+ const finals = states.filter((slug) => machine.isTerminal(slug));
48
+ const lines = ["graph TD;"];
49
+ for (const slug of states) {
50
+ const kind = machine.isHumanState(slug) ? `{{${slug}}}` : `[${slug}]`;
51
+ lines.push(` ${mermaidId(slug)}${kind};`);
52
+ }
53
+ for (const edge of edges) {
54
+ const source = edge.source === "__start__" ? "__start__" : mermaidId(edge.source);
55
+ const arrow = edge.conditional ? "-.->" : "-->";
56
+ const label = edge.label ? `|${edge.label.replace(/\|/g, "/")}|` : "";
57
+ lines.push(` ${source} ${arrow}${label} ${mermaidId(edge.target)};`);
58
+ }
59
+ return {
60
+ nodes: ["__start__", ...states],
61
+ edges,
62
+ entry: machine.entry,
63
+ finals,
64
+ mermaid: `${lines.join("\n")}\n`,
65
+ };
66
+ }
67
+ /** The machine's topology as one log line per state, for the `graph-topology` diagnostic. */
68
+ export function describeMachineTopology(machine) {
69
+ const starts = machine.startStates();
70
+ const startLabel = starts.length
71
+ ? starts.map((s) => `${s.state} (${s.trigger})`).join(" | ")
72
+ : machine.entry;
73
+ const lines = [`START -> ${startLabel}`];
74
+ for (const slug of Object.keys(machine.spec.states)) {
75
+ const targets = machine.transitionTargets(slug);
76
+ const rhs = targets.length ? targets.join(" | ") : "END";
77
+ const kind = machine.isHumanState(slug) ? " [human]" : "";
78
+ lines.push(`${slug}${kind} -> ${rhs}`);
79
+ }
80
+ return lines.join("\n ");
81
+ }
82
+ /**
83
+ * The store as recorded: value and `locked` only. `locked` is the attribution —
84
+ * a locked entry can only come from the host, an unlocked one only from the
85
+ * agent. The in-flight `reseed` marker is dropped: it describes one update's
86
+ * authority within a reducer, never session state.
87
+ */
88
+ function recordedVariables(store) {
89
+ return Object.fromEntries(Object.entries(store).map(([name, entry]) => [name, { value: entry.value, locked: entry.locked }]));
90
+ }
91
+ /**
92
+ * Persist the session's graph, trajectory, audit trail and variables under
93
+ * `<sessionId>/artifacts/`. An absent trail means "unreadable", an empty one "no
94
+ * transitions"; an empty variable store is still written for the same reason.
95
+ * Best-effort: a write failure is a `warning` event and `null`.
96
+ */
97
+ export async function writeRunArtifacts(workspace, workflow, sessionId, artifacts, onEvent) {
98
+ const paths = runArtifactPaths(sessionId);
99
+ const { runId: _legacyId, ...rest } = artifacts.trajectory;
100
+ const trajectory = { sessionId, ...rest };
101
+ try {
102
+ // Independent files, written concurrently: one round trip on a remote session store.
103
+ await Promise.all([
104
+ workspace.writeJson(paths.graphJson, artifacts.graph),
105
+ workspace.writeText(paths.graphMermaid, `${artifacts.graph.mermaid}\n`),
106
+ workspace.writeJson(paths.trajectoryJson, trajectory),
107
+ ...(artifacts.metadata
108
+ ? [workspace.writeJson(paths.metadataJson, { sessionId, workflow, ...artifacts.metadata })]
109
+ : []),
110
+ ...(artifacts.trail
111
+ ? [workspace.writeJson(paths.trailJson, { sessionId, workflow, steps: artifacts.trail })]
112
+ : []),
113
+ ...(artifacts.variables !== undefined
114
+ ? [
115
+ workspace.writeJson(paths.variablesJson, {
116
+ sessionId,
117
+ workflow,
118
+ variables: recordedVariables(artifacts.variables),
119
+ }),
120
+ ]
121
+ : []),
122
+ ]);
123
+ return paths.runDir;
124
+ }
125
+ catch (err) {
126
+ createWorkflowEventEmitter(onEvent)({
127
+ type: "warning",
128
+ scope: "run-artifacts",
129
+ message: `failed to write artifacts for session '${sessionId}': ${err.message}`,
130
+ });
131
+ return null;
132
+ }
133
+ }
134
+ //# sourceMappingURL=session-artifacts.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-artifacts.js","sourceRoot":"","sources":["../../src/workflow/session-artifacts.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,31 @@
1
+ import type { ParkChannel, TrailStep } from "./state.js";
2
+ import type { VariableStore } from "../machine/variables.js";
3
+ export interface ToolCallFact {
4
+ name: string;
5
+ /** The provider tool-call id, when the message carried one. */
6
+ id?: string;
7
+ input: unknown;
8
+ output?: unknown;
9
+ status: "completed" | "pending" | "failed" | "rejected";
10
+ }
11
+ export interface SessionView {
12
+ sessionId: string;
13
+ reply: string;
14
+ failed: boolean;
15
+ parked: boolean;
16
+ /** Which channel a parked run awaits: a person's `decision` or external `input`. */
17
+ parkedChannel?: ParkChannel;
18
+ /** For a parked session view, the state awaiting a decision or an external trigger. */
19
+ node?: string;
20
+ events: Array<{
21
+ type: string;
22
+ data?: Record<string, unknown>;
23
+ }>;
24
+ toolCalls: ToolCallFact[];
25
+ /** The committed audit trail, from checkpointed state — never derived from messages; empty when the producer has none. */
26
+ auditTrail: TrailStep[];
27
+ /** The run's variables from checkpointed state; empty when the producer has none. */
28
+ variables: VariableStore;
29
+ }
30
+ /** Derive a typed session view from LangChain message history. */
31
+ export declare function messagesToSessionView(messages: unknown[], sessionId?: string, auditTrail?: TrailStep[], variables?: VariableStore): SessionView;
@@ -0,0 +1,94 @@
1
+ import { contentToString, isRuntimeNote, messageTypeOf, runtimeNoteKind } from "../core/messages.js";
2
+ function isMessage(m) {
3
+ return (m != null &&
4
+ typeof m === "object" &&
5
+ ("content" in m || typeof m._getType === "function"));
6
+ }
7
+ /** Derive a typed session view from LangChain message history. */
8
+ export function messagesToSessionView(messages, sessionId = "default", auditTrail = [], variables = {}) {
9
+ const list = Array.isArray(messages) ? messages : [];
10
+ const events = [];
11
+ const toolCalls = [];
12
+ let reply = "";
13
+ let failed = false;
14
+ for (const raw of list) {
15
+ if (!isMessage(raw))
16
+ continue;
17
+ const type = messageTypeOf(raw) || "?";
18
+ const msg = raw;
19
+ const text = contentToString(msg.content);
20
+ // A runtime note is shaped as a tool call plus its result, but the agent made
21
+ // no call: it is surfaced as a `runtime.note` event (from the half carrying
22
+ // the text) and never as a tool call, so `calledTool`/`usedNoTools` and the
23
+ // CLI flow do not report an `archmax_note` call the run never made.
24
+ if (isRuntimeNote(raw)) {
25
+ if (type !== "ai" && type !== "assistant") {
26
+ events.push({ type: "runtime.note", data: { kind: runtimeNoteKind(raw), text } });
27
+ }
28
+ continue;
29
+ }
30
+ if (type === "ai" || type === "assistant") {
31
+ if (text)
32
+ reply = text;
33
+ events.push({ type: "message.completed", data: { message: text } });
34
+ const calls = msg.tool_calls;
35
+ if (Array.isArray(calls)) {
36
+ for (const c of calls) {
37
+ const call = c;
38
+ const name = String(call.name ?? "");
39
+ toolCalls.push({
40
+ name,
41
+ id: call.id == null ? undefined : String(call.id),
42
+ input: call.args ?? {},
43
+ status: "pending",
44
+ });
45
+ events.push({ type: "tool.called", data: { name, input: call.args } });
46
+ }
47
+ }
48
+ }
49
+ if (type === "tool") {
50
+ const name = String(msg.name ?? "");
51
+ const rawStatus = String(msg.status ?? "completed");
52
+ // A governance-blocked call carries `status: "error"` (so the model
53
+ // self-corrects) but is a policy rejection, not a run failure: surface it
54
+ // as `rejected` and do not flip the run's `failed` flag.
55
+ const blocked = isGovernanceBlocked(msg);
56
+ const status = blocked
57
+ ? "rejected"
58
+ : rawStatus === "error"
59
+ ? "failed"
60
+ : rawStatus;
61
+ if (status === "failed")
62
+ failed = true;
63
+ const output = unwrapToolContent(msg.content);
64
+ // Match by tool_call_id when the message carries one; interleaved calls
65
+ // to the same tool would otherwise pair with the wrong output. Fall back
66
+ // to name order for providers that omit ids.
67
+ const callId = msg.tool_call_id == null ? undefined : String(msg.tool_call_id);
68
+ const fact = (callId && toolCalls.find((tc) => tc.id === callId && tc.status === "pending")) ||
69
+ toolCalls.find((tc) => tc.name === name && tc.status === "pending" && tc.output === undefined);
70
+ if (fact) {
71
+ fact.output = output;
72
+ fact.status = status;
73
+ }
74
+ events.push({ type: "tool.completed", data: { name, output, status } });
75
+ }
76
+ }
77
+ return { sessionId, reply, failed, parked: false, events, toolCalls, auditTrail, variables };
78
+ }
79
+ function isGovernanceBlocked(msg) {
80
+ const kwargs = msg.additional_kwargs;
81
+ return kwargs?.governance_blocked === true;
82
+ }
83
+ function unwrapToolContent(content) {
84
+ if (typeof content === "string") {
85
+ try {
86
+ return JSON.parse(content);
87
+ }
88
+ catch {
89
+ return content;
90
+ }
91
+ }
92
+ return content;
93
+ }
94
+ //# sourceMappingURL=session-view.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-view.js","sourceRoot":"","sources":["../../src/workflow/session-view.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,14 @@
1
+ import type { MachineSpec } from "../machine/types.js";
2
+ import { type WorkflowEventHandler } from "../core/events.js";
3
+ import type { Workspace } from "../core/workspace.js";
4
+ /** A stable content hash of the machine spec, normalized so cosmetic edits do not change it. */
5
+ export declare function computeSpecHash(spec: MachineSpec): string;
6
+ /**
7
+ * Persist the spec for `hash` unless a snapshot already exists. Idempotent: a
8
+ * hit or a lost write race are both success, since the content is determined by
9
+ * the hash. What is written is the hashed document (without presentation
10
+ * metadata), so two specs sharing a hash cannot differ in bytes.
11
+ */
12
+ export declare function writeSpecSnapshotIfAbsent(workspace: Workspace, hash: string, spec: MachineSpec, onEvent?: WorkflowEventHandler): Promise<void>;
13
+ /** The persisted spec for `specHash`, or `null` when no snapshot exists for it. */
14
+ export declare function readSpecSnapshot(workspace: Workspace, hash: string): Promise<MachineSpec | null>;
@@ -0,0 +1,97 @@
1
+ /**
2
+ * A run's record of the spec it executed: the content hash identifying a
3
+ * machine spec, and the snapshot store that resolves one back.
4
+ */
5
+ import { createHash } from "node:crypto";
6
+ import { createWorkflowEventEmitter } from "../core/events.js";
7
+ import { specSnapshotPath } from "./paths.js";
8
+ /** Serialize with object keys sorted at every level; arrays keep their order (sequence is semantic). */
9
+ function stableStringify(value) {
10
+ if (value === null || typeof value !== "object")
11
+ return JSON.stringify(value) ?? "null";
12
+ if (Array.isArray(value))
13
+ return `[${value.map(stableStringify).join(",")}]`;
14
+ const entries = Object.entries(value)
15
+ .filter(([, v]) => v !== undefined)
16
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
17
+ .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
18
+ return `{${entries.join(",")}}`;
19
+ }
20
+ /** Drop a `metadata` block from one object, returning it unchanged when it has none. */
21
+ function withoutMetadata(value) {
22
+ if (value.metadata === undefined)
23
+ return value;
24
+ const { metadata: _metadata, ...rest } = value;
25
+ return rest;
26
+ }
27
+ /**
28
+ * Strip `metadata` from every inline rubric in one `before`/`after` field,
29
+ * preserving the field's own shape (a single hook stays a single hook).
30
+ */
31
+ function hooksWithoutMetadata(field) {
32
+ const strip = (hook) => {
33
+ const declaration = hook?.rubric;
34
+ if (!declaration || typeof declaration !== "object" || declaration.metadata === undefined) {
35
+ return hook;
36
+ }
37
+ return { ...hook, rubric: withoutMetadata(declaration) };
38
+ };
39
+ return Array.isArray(field) ? field.map(strip) : strip(field);
40
+ }
41
+ /**
42
+ * The spec as a machine: every runtime-inert `metadata` block removed — at the
43
+ * root, on each state, and on each rubric inlined in a state's hooks — so a
44
+ * canvas edit does not mint a new spec version. Returns the spec itself when
45
+ * there is nothing to drop, so specs without the block hash unchanged.
46
+ */
47
+ function governingSpec(spec) {
48
+ const stateHasMetadata = ([, state]) => state?.metadata !== undefined ||
49
+ ["before", "after"].some((phase) => hooksWithoutMetadata(state?.[phase]) !== state?.[phase]);
50
+ const states = Object.entries(spec.states ?? {});
51
+ if (spec.metadata === undefined && !states.some(stateHasMetadata))
52
+ return spec;
53
+ return {
54
+ ...withoutMetadata(spec),
55
+ states: Object.fromEntries(states.map(([slug, state]) => {
56
+ const governed = withoutMetadata(state ?? {});
57
+ for (const phase of ["before", "after"]) {
58
+ if (governed[phase] === undefined)
59
+ continue;
60
+ governed[phase] = hooksWithoutMetadata(governed[phase]);
61
+ }
62
+ return [slug, governed];
63
+ })),
64
+ };
65
+ }
66
+ /** A stable content hash of the machine spec, normalized so cosmetic edits do not change it. */
67
+ export function computeSpecHash(spec) {
68
+ return createHash("sha256").update(stableStringify(governingSpec(spec))).digest("hex").slice(0, 32);
69
+ }
70
+ /**
71
+ * Persist the spec for `hash` unless a snapshot already exists. Idempotent: a
72
+ * hit or a lost write race are both success, since the content is determined by
73
+ * the hash. What is written is the hashed document (without presentation
74
+ * metadata), so two specs sharing a hash cannot differ in bytes.
75
+ */
76
+ export async function writeSpecSnapshotIfAbsent(workspace, hash, spec, onEvent) {
77
+ const path = specSnapshotPath(hash);
78
+ if (await workspace.exists(path))
79
+ return;
80
+ try {
81
+ await workspace.writeJson(path, governingSpec(spec));
82
+ }
83
+ catch (err) {
84
+ if (await workspace.exists(path))
85
+ return;
86
+ createWorkflowEventEmitter(onEvent)({
87
+ type: "warning",
88
+ scope: "spec-snapshot",
89
+ message: `failed to persist spec snapshot for hash '${hash}': ${err.message}`,
90
+ });
91
+ }
92
+ }
93
+ /** The persisted spec for `specHash`, or `null` when no snapshot exists for it. */
94
+ export async function readSpecSnapshot(workspace, hash) {
95
+ return workspace.readJson(specSnapshotPath(hash));
96
+ }
97
+ //# sourceMappingURL=snapshot.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/workflow/snapshot.ts"],"names":[],"mappings":"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"}