@ptkl/toolkit 1.3.0 → 1.4.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 (61) hide show
  1. package/README.md +37 -30
  2. package/dist/bin/toolkit.js +37 -3
  3. package/dist/commands/__tests__/apiUsers.test.js +16 -0
  4. package/dist/commands/__tests__/forge-requires.test.js +58 -0
  5. package/dist/commands/__tests__/profile.test.js +65 -0
  6. package/dist/commands/apiUsers.js +12 -0
  7. package/dist/commands/forge.js +82 -6
  8. package/dist/commands/profile.js +84 -76
  9. package/dist/lib/kortex/__tests__/fixtures/providers/conformance.test.js +120 -0
  10. package/dist/lib/kortex/__tests__/fixtures/sse-and-persistence.test.js +172 -0
  11. package/dist/lib/kortex/__tests__/legacy-compatibility.test.js +273 -0
  12. package/dist/lib/kortex/__tests__/phase-1-conversion.test.js +154 -0
  13. package/dist/lib/kortex/__tests__/phase-2-runtime.test.js +100 -0
  14. package/dist/lib/kortex/__tests__/phase-3-provider.test.js +48 -0
  15. package/dist/lib/kortex/config/loader.js +129 -0
  16. package/dist/lib/kortex/config/schema.js +60 -0
  17. package/dist/lib/kortex/controller.js +60 -0
  18. package/dist/lib/kortex/conversation/legacy-conversion.js +141 -0
  19. package/dist/lib/kortex/conversation/types.js +13 -0
  20. package/dist/lib/kortex/events/index.js +1 -0
  21. package/dist/lib/kortex/events/reducer.js +86 -0
  22. package/dist/lib/kortex/events/types.js +7 -0
  23. package/dist/lib/kortex/events/writer.js +76 -0
  24. package/dist/lib/kortex/mcp/index.js +1 -0
  25. package/dist/lib/kortex/orchestration/index.js +1 -0
  26. package/dist/lib/kortex/orchestration/manager-worker.js +88 -0
  27. package/dist/lib/kortex/orchestration/peer-collaboration.js +59 -0
  28. package/dist/lib/kortex/orchestration/plan.js +133 -0
  29. package/dist/lib/kortex/orchestration/scheduler.js +124 -0
  30. package/dist/lib/kortex/persistence/index.js +1 -0
  31. package/dist/lib/kortex/persistence/run-journal.js +94 -0
  32. package/dist/lib/kortex/providers/anthropic.js +34 -0
  33. package/dist/lib/kortex/providers/index.js +1 -0
  34. package/dist/lib/kortex/providers/openai-compatible.js +190 -0
  35. package/dist/lib/kortex/providers/protokol.js +204 -0
  36. package/dist/lib/kortex/providers/registry.js +61 -0
  37. package/dist/lib/kortex/providers/types.js +13 -0
  38. package/dist/lib/kortex/runtime/agent-runner.js +241 -0
  39. package/dist/lib/kortex/runtime/approval-queue.js +95 -0
  40. package/dist/lib/kortex/runtime/budget-controller.js +105 -0
  41. package/dist/lib/kortex/runtime/index.js +1 -0
  42. package/dist/lib/kortex/runtime/tool-runtime.js +66 -0
  43. package/dist/lib/kortex/runtime/workspace.js +52 -0
  44. package/dist/lib/kortex/tools/index.js +1 -0
  45. package/dist/lib/kortex/tools.js +226 -34
  46. package/dist/lib/kortex/types.js +7 -0
  47. package/dist/lib/kortex/ui/index.js +1 -0
  48. package/dist/lib/oauth/CallbackPages.js +82 -0
  49. package/dist/lib/oauth/CallbackServer.js +84 -0
  50. package/dist/lib/oauth/OAuthClient.js +81 -0
  51. package/dist/lib/oauth/OAuthError.js +17 -0
  52. package/dist/lib/oauth/OAuthLogin.js +60 -0
  53. package/dist/lib/oauth/OAuthSession.js +100 -0
  54. package/dist/lib/oauth/Pkce.js +19 -0
  55. package/dist/lib/oauth/ProfileLogin.js +76 -0
  56. package/dist/lib/oauth/RefreshLock.js +61 -0
  57. package/dist/lib/oauth/ScopePreset.js +38 -0
  58. package/dist/lib/oauth/__tests__/mockServer.js +29 -0
  59. package/dist/lib/oauth/__tests__/oauth.test.js +347 -0
  60. package/dist/lib/util.js +9 -2
  61. package/package.json +6 -4
@@ -0,0 +1,129 @@
1
+ /**
2
+ * Config loader — resolves, merges, and validates Kortex configuration.
3
+ *
4
+ * Source order (later overrides earlier):
5
+ * 1. Built-in defaults
6
+ * 2. Legacy ~/.ptkl/kortex.json (compatibility import)
7
+ * 3. ~/.ptkl/kortex/config.json
8
+ * 4. Legacy <project>/.ptkl/kortex.json (compatibility import)
9
+ * 5. <project>/.kortex.json
10
+ * 6. CLI flags / runtime overrides
11
+ *
12
+ * Arrays are replaced unless a field explicitly defines keyed merge behavior.
13
+ * Agents and providers merge by object key. null removes an inherited entry.
14
+ */
15
+ import { readFileSync, existsSync } from 'node:fs';
16
+ import { resolve } from 'node:path';
17
+ const API_KEY_PATTERNS = [
18
+ /^api[_-]?key$/i,
19
+ /^api[_-]?token$/i,
20
+ /^secret_key$/i,
21
+ /^secret$/i,
22
+ /^token$/i,
23
+ ];
24
+ /**
25
+ * Resolve configuration from the project and global config files.
26
+ */
27
+ export function loadConfig(cwd) {
28
+ const errors = [];
29
+ let config = {};
30
+ const configPaths = [
31
+ resolve(process.env.HOME || '~', '.ptkl', 'kortex.json'),
32
+ resolve(process.env.HOME || '~', '.ptkl', 'kortex', 'config.json'),
33
+ resolve(cwd, '.ptkl', 'kortex.json'),
34
+ resolve(cwd, '.kortex.json'),
35
+ ];
36
+ for (const path of configPaths) {
37
+ if (!existsSync(path))
38
+ continue;
39
+ try {
40
+ const data = JSON.parse(readFileSync(path, 'utf-8'));
41
+ config = mergeConfigs(config, data, path, errors);
42
+ }
43
+ catch (e) {
44
+ errors.push({ path, message: `Failed to parse: ${e.message}`, severity: 'error' });
45
+ }
46
+ }
47
+ // Validate
48
+ const validationErrors = validateConfig(config);
49
+ errors.push(...validationErrors);
50
+ return { config, errors };
51
+ }
52
+ /**
53
+ * Merge two config objects. Agents and providers merge by key; arrays replace.
54
+ */
55
+ function mergeConfigs(base, override, sourcePath, errors) {
56
+ // Providers: merge by key
57
+ const providers = { ...(base.providers || {}), ...(override.providers || {}) };
58
+ // Agents: merge by key
59
+ const agents = { ...(base.agents || {}), ...(override.agents || {}) };
60
+ // Orchestrator: shallow merge (last wins for each field)
61
+ const orchestrator = { ...(base.orchestrator || {}), ...(override.orchestrator || {}) };
62
+ // MCP: merge by key
63
+ const mcp_servers = { ...(base.mcp_servers || {}), ...(override.mcp_servers || {}) };
64
+ return { version: override.version ?? base.version, providers, agents, orchestrator, mcp_servers };
65
+ }
66
+ /**
67
+ * Validate a fully merged config.
68
+ */
69
+ function validateConfig(config) {
70
+ const errors = [];
71
+ // Version check
72
+ if (config.version !== undefined && config.version !== 1) {
73
+ errors.push({ path: 'version', message: `Unsupported config version: ${config.version}`, severity: 'error' });
74
+ }
75
+ // Validate providers
76
+ for (const [name, provider] of Object.entries(config.providers ?? {})) {
77
+ // Check for plaintext secrets
78
+ for (const [key, value] of Object.entries(provider)) {
79
+ if (typeof value === 'string' && API_KEY_PATTERNS.some(p => p.test(key))) {
80
+ errors.push({
81
+ path: `providers.${name}.${key}`,
82
+ message: `Plaintext ${key} detected. Use api_key_env to reference an environment variable instead.`,
83
+ severity: 'error',
84
+ });
85
+ }
86
+ }
87
+ // Check api_key_env references
88
+ if (provider.api_key_env && !process.env[provider.api_key_env]) {
89
+ errors.push({
90
+ path: `providers.${name}.api_key_env`,
91
+ message: `Environment variable "${provider.api_key_env}" is not set.`,
92
+ severity: 'error',
93
+ });
94
+ }
95
+ // Reserved MCP server name
96
+ if (name === 'protokol' && provider.type !== 'protokol') {
97
+ errors.push({
98
+ path: `providers.${name}`,
99
+ message: '"protokol" is a reserved provider name.',
100
+ severity: 'error',
101
+ });
102
+ }
103
+ }
104
+ // Validate agents
105
+ for (const [name, agent] of Object.entries(config.agents ?? {})) {
106
+ if (!agent.provider) {
107
+ errors.push({ path: `agents.${name}.provider`, message: 'Agent must specify a provider.', severity: 'error' });
108
+ }
109
+ else if (!config.providers?.[agent.provider]) {
110
+ errors.push({ path: `agents.${name}.provider`, message: `Provider "${agent.provider}" not found in providers section.`, severity: 'error' });
111
+ }
112
+ if (!agent.target) {
113
+ errors.push({ path: `agents.${name}.target`, message: 'Agent must specify a target.', severity: 'error' });
114
+ }
115
+ }
116
+ return errors;
117
+ }
118
+ /**
119
+ * Validate MCP config — no user server may be named "protokol".
120
+ */
121
+ export function validateMCPConfig(mcp_servers) {
122
+ const errors = [];
123
+ for (const name of Object.keys(mcp_servers || {})) {
124
+ if (name === 'protokol') {
125
+ errors.push({ path: `mcp_servers.${name}`, message: '"protokol" is a reserved MCP server ID. Remove this entry.', severity: 'error' });
126
+ }
127
+ }
128
+ return errors;
129
+ }
@@ -0,0 +1,60 @@
1
+ /**
2
+ * JSON Schema for .kortex.json config files.
3
+ * Used for validation on load. Phase 3+.
4
+ */
5
+ export const KORTEX_CONFIG_SCHEMA = {
6
+ $schema: 'http://json-schema.org/draft-07/schema#',
7
+ title: 'KortexConfig',
8
+ type: 'object',
9
+ properties: {
10
+ version: { type: 'number', enum: [1] },
11
+ providers: {
12
+ type: 'object',
13
+ additionalProperties: {
14
+ type: 'object',
15
+ properties: {
16
+ type: { type: 'string', enum: ['protokol', 'openai', 'openai-compatible', 'anthropic', 'google', 'custom'] },
17
+ api_key_env: { type: 'string' },
18
+ base_url: { type: 'string', format: 'uri' },
19
+ auth: { type: 'string' },
20
+ default_model: { type: 'string' },
21
+ },
22
+ required: ['type'],
23
+ },
24
+ },
25
+ agents: {
26
+ type: 'object',
27
+ additionalProperties: {
28
+ type: 'object',
29
+ properties: {
30
+ description: { type: 'string' },
31
+ provider: { type: 'string' },
32
+ target: {
33
+ oneOf: [
34
+ { type: 'object', properties: { type: { const: 'model' }, model: { type: 'string' } }, required: ['type', 'model'] },
35
+ { type: 'object', properties: { type: { const: 'provider_agent' }, id: { type: 'string' } }, required: ['type', 'id'] },
36
+ ],
37
+ },
38
+ instructions: {
39
+ type: 'object',
40
+ properties: {
41
+ type: { type: 'string', enum: ['inline', 'file', 'provider_managed'] },
42
+ text: { type: 'string' },
43
+ path: { type: 'string' },
44
+ },
45
+ required: ['type'],
46
+ },
47
+ tools: {
48
+ type: 'object',
49
+ properties: {
50
+ allow: { type: 'array', items: { type: 'string' } },
51
+ deny: { type: 'array', items: { type: 'string' } },
52
+ riskCeiling: { type: 'string', enum: ['read', 'write', 'execute', 'external'] },
53
+ },
54
+ },
55
+ },
56
+ required: ['description', 'provider', 'target', 'instructions'],
57
+ },
58
+ },
59
+ },
60
+ };
@@ -0,0 +1,60 @@
1
+ /**
2
+ * KortexController — routes between legacy ChatSession and orchestration sessions.
3
+ *
4
+ * Phase 2: the new runner runs behind a feature flag (KORTEX_NEW_RUNNER).
5
+ * Default is legacy Session for backward compatibility.
6
+ *
7
+ * Phase 4+: the new runner becomes the default; legacy Session is removed.
8
+ */
9
+ import LegacySession from './session.js';
10
+ import { createDefaultRegistry } from './providers/registry.js';
11
+ import { ProtokolAdapter } from './providers/protokol.js';
12
+ import { ToolRuntime } from './runtime/tool-runtime.js';
13
+ import { ApprovalQueue } from './runtime/approval-queue.js';
14
+ import { BudgetController, DEFAULT_RUN_BUDGETS } from './runtime/budget-controller.js';
15
+ import { AgentRunner as NewAgentRunner } from './runtime/agent-runner.js';
16
+ import { RunEventReducer } from './events/reducer.js';
17
+ /**
18
+ * Create and start the appropriate session based on the feature flag.
19
+ */
20
+ export async function startSession(opts) {
21
+ const useNewRunner = process.env.KORTEX_NEW_RUNNER === '1';
22
+ if (useNewRunner) {
23
+ await startNewRunner(opts);
24
+ }
25
+ else {
26
+ await startLegacySession(opts);
27
+ }
28
+ }
29
+ async function startNewRunner(opts) {
30
+ // Build provider registry with Protokol adapter
31
+ const registry = createDefaultRegistry();
32
+ const protokolAdapter = new ProtokolAdapter({
33
+ host: opts.host,
34
+ token: opts.token,
35
+ agentUUID: opts.agentUUID,
36
+ });
37
+ registry.register(protokolAdapter);
38
+ // Build runtime
39
+ const toolRuntime = new ToolRuntime();
40
+ const approvalQueue = new ApprovalQueue();
41
+ const budgetController = new BudgetController(DEFAULT_RUN_BUDGETS);
42
+ const agentRunner = new NewAgentRunner(toolRuntime, approvalQueue, budgetController);
43
+ const reducer = new RunEventReducer();
44
+ // Phase 4+: orchestration session
45
+ opts.bridge.showSystem('Kortex new runner initialized (experimental).');
46
+ }
47
+ async function startLegacySession(opts) {
48
+ const session = new LegacySession({
49
+ token: opts.token,
50
+ host: opts.host,
51
+ agentUUID: opts.agentUUID,
52
+ agentName: opts.agentName,
53
+ cwd: opts.cwd,
54
+ conversationUUID: opts.conversationUUID,
55
+ initialPrompt: opts.initialPrompt,
56
+ cloud: opts.cloud,
57
+ bridge: opts.bridge,
58
+ });
59
+ await session.start();
60
+ }
@@ -0,0 +1,141 @@
1
+ /**
2
+ * Conversion between the legacy StoredMessage format and the canonical Turn model.
3
+ *
4
+ * Used during migration so existing stored conversations remain readable
5
+ * while new code paths produce Turns.
6
+ */
7
+ import { randomUUID as uuid } from 'node:crypto';
8
+ /**
9
+ * Convert a single legacy StoredMessage to one or more Turns.
10
+ *
11
+ * Legacy messages have a single `content: string` and optional `tool_calls`.
12
+ * The canonical model uses ordered ContentBlocks — one text block for content,
13
+ * separate blocks for tool calls and tool results.
14
+ */
15
+ export function storedMessageToTurns(msg) {
16
+ const now = new Date().toISOString();
17
+ const turns = [];
18
+ if (msg.role === 'tool') {
19
+ // Legacy tool result messages: content is the output, tool_call_id links
20
+ // back to the original call.
21
+ turns.push({
22
+ id: uuid(),
23
+ role: 'tool',
24
+ createdAt: now,
25
+ blocks: [
26
+ {
27
+ type: 'tool_result',
28
+ callId: msg.tool_call_id ?? 'unknown',
29
+ name: '',
30
+ output: { text: msg.content, truncated: false },
31
+ isError: msg.content.startsWith('Error:'),
32
+ },
33
+ ],
34
+ });
35
+ }
36
+ else if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
37
+ // Legacy assistant messages with tool_calls: content + parallel tool calls.
38
+ const blocks = [];
39
+ if (msg.content) {
40
+ blocks.push({ type: 'text', text: msg.content });
41
+ }
42
+ for (const tc of msg.tool_calls) {
43
+ let args = {};
44
+ try {
45
+ args = JSON.parse(tc.function?.arguments ?? '{}');
46
+ }
47
+ catch { /* keep empty */ }
48
+ blocks.push({
49
+ type: 'tool_call',
50
+ id: tc.id ?? uuid(),
51
+ name: tc.function?.name ?? 'unknown',
52
+ arguments: args,
53
+ rawArguments: tc.function?.arguments,
54
+ });
55
+ }
56
+ turns.push({ id: uuid(), role: 'assistant', createdAt: now, blocks });
57
+ }
58
+ else if (msg.role === 'context') {
59
+ // Context messages become a system-role turn (not user)
60
+ turns.push({
61
+ id: uuid(),
62
+ role: 'system',
63
+ createdAt: now,
64
+ blocks: [{ type: 'text', text: msg.content }],
65
+ });
66
+ }
67
+ else {
68
+ // Standard user or assistant text message
69
+ turns.push({
70
+ id: uuid(),
71
+ role: msg.role === 'assistant' ? 'assistant' : 'user',
72
+ createdAt: now,
73
+ blocks: msg.content ? [{ type: 'text', text: msg.content }] : [],
74
+ });
75
+ }
76
+ return turns;
77
+ }
78
+ /**
79
+ * Convert a full array of legacy stored messages to canonical Turns.
80
+ */
81
+ export function storedMessagesToTurns(messages) {
82
+ return messages.flatMap(storedMessageToTurns);
83
+ }
84
+ /**
85
+ * Convert canonical Turns back to legacy StoredMessages (for backward compat saves).
86
+ * Collapses consecutive assistant+tool_calls+tool_result sequences.
87
+ */
88
+ export function turnsToStoredMessages(turns) {
89
+ const msgs = [];
90
+ for (const turn of turns) {
91
+ const textBlocks = turn.blocks.filter((b) => b.type === 'text');
92
+ const toolCallBlocks = turn.blocks.filter((b) => b.type === 'tool_call');
93
+ const toolResultBlocks = turn.blocks.filter((b) => b.type === 'tool_result');
94
+ const reasoningBlocks = turn.blocks.filter((b) => b.type === 'reasoning_summary');
95
+ if (turn.role === 'tool') {
96
+ // Each tool_result block becomes one tool message
97
+ for (const tr of toolResultBlocks) {
98
+ msgs.push({
99
+ role: 'tool',
100
+ content: tr.output.text,
101
+ tool_call_id: tr.callId,
102
+ });
103
+ }
104
+ }
105
+ else if (toolCallBlocks.length > 0) {
106
+ // Assistant message with tool calls
107
+ const combinedContent = textBlocks.map(b => b.text).join('\n');
108
+ const msg = {
109
+ role: 'assistant',
110
+ content: combinedContent,
111
+ tool_calls: toolCallBlocks.map(tc => ({
112
+ id: tc.id,
113
+ type: 'function',
114
+ function: {
115
+ name: tc.name,
116
+ arguments: tc.rawArguments ?? JSON.stringify(tc.arguments),
117
+ },
118
+ })),
119
+ };
120
+ msgs.push(msg);
121
+ }
122
+ else if (turn.role === 'system') {
123
+ // System turns become context messages
124
+ const content = textBlocks.map(b => b.text).join('\n');
125
+ if (content) {
126
+ msgs.push({ role: 'context', content });
127
+ }
128
+ }
129
+ else {
130
+ // Standard text turn
131
+ const content = [...textBlocks, ...reasoningBlocks].map(b => ('text' in b ? b.text : '')).join('\n');
132
+ if (content || turn.blocks.length === 0) {
133
+ msgs.push({
134
+ role: turn.role === 'assistant' ? 'assistant' : 'user',
135
+ content,
136
+ });
137
+ }
138
+ }
139
+ }
140
+ return msgs;
141
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Canonical conversation model — Turn and ContentBlock types.
3
+ *
4
+ * This is the provider-neutral intermediate representation for all LLM
5
+ * conversations. Every provider adapter converts to/from this model.
6
+ *
7
+ * Key design:
8
+ * - Ordered content blocks rather than a single content string.
9
+ * - ProviderState as an opaque escape hatch for provider-specific
10
+ * continuation tokens, thinking signatures, etc.
11
+ * - ArtifactRef for cross-worker file/result references.
12
+ */
13
+ export {};
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,86 @@
1
+ /**
2
+ * In-memory event reducer — builds a readable run summary from a stream of RunEvents.
3
+ *
4
+ * Usage:
5
+ * const reducer = new RunEventReducer()
6
+ * for (const envelope of eventStream) {
7
+ * reducer.apply(envelope)
8
+ * }
9
+ * console.log(reducer.summary())
10
+ */
11
+ export class RunEventReducer {
12
+ state = null;
13
+ apply(envelope) {
14
+ const { runId, event } = envelope;
15
+ if (!this.state || this.state.runId !== runId) {
16
+ this.state = this.createInitialState(runId);
17
+ }
18
+ const s = this.state;
19
+ switch (event.type) {
20
+ case 'plan.approved':
21
+ s.planApproved = true;
22
+ break;
23
+ case 'task.state': {
24
+ let ts = s.tasks.get(event.taskId);
25
+ if (!ts) {
26
+ ts = { taskId: event.taskId, state: event.state, attempt: event.attempt, toolCalls: 0 };
27
+ s.tasks.set(event.taskId, ts);
28
+ }
29
+ ts.state = event.state;
30
+ ts.attempt = event.attempt;
31
+ if (event.error)
32
+ ts.error = event.error;
33
+ break;
34
+ }
35
+ case 'tool.completed':
36
+ for (const ts of s.tasks.values()) {
37
+ if (ts.taskId === event.taskId)
38
+ ts.toolCalls++;
39
+ }
40
+ s.totalToolCalls++;
41
+ break;
42
+ case 'usage.updated':
43
+ s.totalTokens.input += event.usage.inputTokens ?? 0;
44
+ s.totalTokens.output += event.usage.outputTokens ?? 0;
45
+ break;
46
+ case 'run.finished':
47
+ s.status = 'finished';
48
+ s.outcome = event.outcome;
49
+ break;
50
+ case 'run.cancel_requested':
51
+ s.status = 'finished';
52
+ s.outcome = { kind: 'cancelled', by: 'user', reason: event.reason };
53
+ break;
54
+ }
55
+ s.lastEvent = event;
56
+ return s;
57
+ }
58
+ createInitialState(runId) {
59
+ return {
60
+ runId,
61
+ status: 'running',
62
+ planApproved: false,
63
+ tasks: new Map(),
64
+ totalTokens: { input: 0, output: 0 },
65
+ totalToolCalls: 0,
66
+ lastEvent: null,
67
+ };
68
+ }
69
+ summary() {
70
+ if (!this.state)
71
+ return 'No run data.';
72
+ const s = this.state;
73
+ const lines = [
74
+ `Run: ${s.runId.slice(0, 8)} Status: ${s.status}`,
75
+ `Plan approved: ${s.planApproved}`,
76
+ `Tasks: ${s.tasks.size} Tool calls: ${s.totalToolCalls}`,
77
+ `Tokens: ${s.totalTokens.input} in / ${s.totalTokens.output} out`,
78
+ ];
79
+ for (const ts of s.tasks.values()) {
80
+ lines.push(` ${ts.state.padEnd(20)} ${ts.taskId.slice(0, 8)} att:${ts.attempt} tc:${ts.toolCalls}`);
81
+ }
82
+ if (s.outcome)
83
+ lines.push(`Outcome: ${s.outcome.kind}`);
84
+ return lines.join('\n');
85
+ }
86
+ }
@@ -0,0 +1,7 @@
1
+ /**
2
+ * RunEvent types — the typed event system that drives the orchestrator.
3
+ *
4
+ * Every meaningful transition emits a typed RunEvent wrapped in a
5
+ * RunEventEnvelope with sequence numbering for durability.
6
+ */
7
+ export {};
@@ -0,0 +1,76 @@
1
+ /**
2
+ * JSONL event writer — append-only file-based persistence for RunEvents.
3
+ *
4
+ * Each line is a RunEventEnvelope JSON blob. Append semantics make it
5
+ * crash-tolerant: a partial last line is detected on read and discarded.
6
+ *
7
+ * Phase 1: in-memory + file append. Phase 5 adds snapshot/checksum/resume logic.
8
+ */
9
+ import { appendFileSync, readFileSync, existsSync } from 'node:fs';
10
+ export class EventJournal {
11
+ path;
12
+ sequence = 0;
13
+ lastWritten = '';
14
+ constructor(path) {
15
+ this.path = path;
16
+ }
17
+ /**
18
+ * Append one event to the journal file.
19
+ * Returns the assigned sequence number.
20
+ */
21
+ append(envelope) {
22
+ const seq = ++this.sequence;
23
+ const record = {
24
+ ...envelope,
25
+ sequence: seq,
26
+ at: envelope.at || new Date().toISOString(),
27
+ };
28
+ const line = JSON.stringify(record) + '\n';
29
+ try {
30
+ appendFileSync(this.path, line, 'utf-8');
31
+ this.lastWritten = line;
32
+ }
33
+ catch {
34
+ // Write failures are non-fatal during Phase 1 prototyping
35
+ }
36
+ return seq;
37
+ }
38
+ /**
39
+ * Read all events since a given sequence number.
40
+ * Detects and discards a trailing incomplete line on read.
41
+ */
42
+ readFrom(afterSequence = 0) {
43
+ if (!existsSync(this.path))
44
+ return [];
45
+ const content = readFileSync(this.path, 'utf-8').trimEnd();
46
+ if (!content)
47
+ return [];
48
+ const lines = content.split('\n');
49
+ const events = [];
50
+ for (let i = 0; i < lines.length; i++) {
51
+ const line = lines[i].trim();
52
+ if (!line)
53
+ continue;
54
+ try {
55
+ const parsed = JSON.parse(line);
56
+ // Skip trailing incomplete lines (last line may be partial on crash)
57
+ if (i === lines.length - 1 && line.length < 20)
58
+ continue;
59
+ if (parsed.sequence && parsed.sequence > afterSequence) {
60
+ events.push(parsed);
61
+ }
62
+ }
63
+ catch {
64
+ // Malformed line — skip (likely a partial write)
65
+ continue;
66
+ }
67
+ }
68
+ return events;
69
+ }
70
+ /**
71
+ * Get the last written event (for crash recovery checkpointing).
72
+ */
73
+ get lastSequence() {
74
+ return this.sequence;
75
+ }
76
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,88 @@
1
+ /**
2
+ * Manager-worker orchestration pattern.
3
+ *
4
+ * The orchestrator (manager) plans, dispatches to workers, and
5
+ * synthesizes results. Workers run independently with the tool loop.
6
+ */
7
+ import { Scheduler } from './scheduler.js';
8
+ import { validatePlan } from './plan.js';
9
+ import { AgentRunner } from '../runtime/agent-runner.js';
10
+ import { ToolRuntime } from '../runtime/tool-runtime.js';
11
+ import { ApprovalQueue } from '../runtime/approval-queue.js';
12
+ import { BudgetController, DEFAULT_RUN_BUDGETS } from '../runtime/budget-controller.js';
13
+ /**
14
+ * Run a manager-worker orchestration.
15
+ */
16
+ export async function runManagerWorker(opts) {
17
+ const { plan, agents, provider, tools, runId, signal } = opts;
18
+ const taskResults = new Map();
19
+ // Build available tools map
20
+ const toolMap = new Map(tools.map(t => [t.function.name, t]));
21
+ // Validate plan
22
+ const validation = validatePlan(plan, agents, toolMap, DEFAULT_RUN_BUDGETS.maxTasks);
23
+ if (!validation.valid) {
24
+ return {
25
+ taskResults,
26
+ status: 'failed',
27
+ summary: `Plan validation failed: ${validation.errors.join('; ')}`,
28
+ };
29
+ }
30
+ // Build runtime
31
+ const toolRuntime = new ToolRuntime();
32
+ const approvalQueue = new ApprovalQueue();
33
+ const budgetController = new BudgetController(DEFAULT_RUN_BUDGETS);
34
+ const agentRunner = new AgentRunner(toolRuntime, approvalQueue, budgetController);
35
+ // Create scheduler
36
+ const scheduler = new Scheduler(plan.tasks, DEFAULT_RUN_BUDGETS.maxConcurrency, async (task) => {
37
+ if (signal.aborted)
38
+ return 'cancelled';
39
+ const agent = agents.get(task.agent);
40
+ if (!agent)
41
+ return 'failed';
42
+ const result = await agentRunner.run({
43
+ runId,
44
+ task,
45
+ attempt: 1,
46
+ agent,
47
+ context: {
48
+ goal: plan.goal,
49
+ taskPrompt: task.prompt,
50
+ dependencySummaries: [],
51
+ constraints: [],
52
+ contextBudgetTokens: 64_000,
53
+ },
54
+ workspace: { id: 'shared', kind: 'shared', root: process.cwd(), writable: task.mode === 'write' },
55
+ budgets: budgetController.acquire({ modelCalls: 10 }),
56
+ signal,
57
+ }, provider);
58
+ taskResults.set(task.id, result);
59
+ if (result.status === 'budget_exceeded')
60
+ return 'budget_exceeded';
61
+ if (result.status === 'cancelled')
62
+ return 'cancelled';
63
+ if (result.status === 'failed')
64
+ return 'failed';
65
+ if (result.status === 'needs_user')
66
+ return 'failed';
67
+ return 'succeeded';
68
+ });
69
+ const records = await scheduler.run();
70
+ // Determine overall status
71
+ let allSucceeded = true;
72
+ let anyCancelled = false;
73
+ for (const [, r] of records) {
74
+ if (r.status === 'failed')
75
+ allSucceeded = false;
76
+ if (r.status === 'cancelled') {
77
+ allSucceeded = false;
78
+ anyCancelled = true;
79
+ }
80
+ }
81
+ const status = anyCancelled ? 'cancelled'
82
+ : allSucceeded ? 'succeeded'
83
+ : 'completed_with_issues';
84
+ const summary = `Manager-worker run completed: ${status}. Tasks: ${records.size} total, ` +
85
+ `${Array.from(records.values()).filter(r => r.status === 'succeeded').length} succeeded, ` +
86
+ `${Array.from(records.values()).filter(r => r.status === 'failed').length} failed.`;
87
+ return { taskResults, status, summary };
88
+ }