@gobing-ai/ts-ai-runner 0.4.13 → 0.4.15

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 (5) hide show
  1. package/dist/ai-runner.d.ts +28 -0
  2. package/dist/ai-runner.d.ts.map +1 -1
  3. package/dist/ai-runner.js +44 -0
  4. package/package.json +4 -4
  5. package/src/ai-runner.ts +45 -0
package/dist/ai-runner.d.ts CHANGED
@@ -34,6 +34,34 @@ export interface AgentRunCorrelation {
34
34
  readonly executionId: string;
35
35
  readonly actionId?: string;
36
36
  }
37
+ /**
38
+ * Public environment-variable contract for agent run correlation.
39
+ *
40
+ * When `AgentRunOptions.correlation` is supplied, `AiRunner` forwards these
41
+ * identifiers into the agent subprocess environment via `ProcessOptions.env`.
42
+ * execa's default `extendEnv: true` merges them with the parent process
43
+ * environment, so they are additive — and because environment inheritance is
44
+ * transitive, every descendant of the run inherits the same values.
45
+ *
46
+ * Nesting semantics: **one id per run, shared by all descendants.** Depth is
47
+ * not observable. The consumer's question is "am I inside a run?", which the
48
+ * presence of `SPUR_RUN_ID` answers exactly; a depth counter was rejected as
49
+ * contract with no current consumer (see task 0056 Design).
50
+ *
51
+ * Prefix choice: **`SPUR_`**. The first consumer (Spur's `SessionStart`
52
+ * hook) already reads `SPUR_AGENT` / `SPUR_MODEL` from this environment, so a
53
+ * single vocabulary in one resolver beats a vendor-neutral prefix that forces
54
+ * that resolver to learn a second one. The prefix is a stable public contract;
55
+ * these names cannot be renamed in lockstep with consumers.
56
+ *
57
+ * Only correlation identifiers are forwarded — never tokens, keys, prompts, or
58
+ * user content.
59
+ */
60
+ export declare const AGENT_RUN_ID_ENV = "SPUR_RUN_ID";
61
+ /** Execution-id leg of the correlation env contract (see block comment above). */
62
+ export declare const AGENT_EXECUTION_ID_ENV = "SPUR_EXECUTION_ID";
63
+ /** Optional action-id leg of the correlation env contract (see block comment above). */
64
+ export declare const AGENT_ACTION_ID_ENV = "SPUR_ACTION_ID";
37
65
  /** Constructor options for AiRunner. */
38
66
  export interface AiRunnerOptions {
39
67
  /** Process executor used for all subprocess invocations. */
package/dist/ai-runner.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ai-runner.d.ts","sourceRoot":"","sources":["../src/ai-runner.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"ai-runner.d.ts","sourceRoot":"","sources":["../src/ai-runner.ts"],"names":[],"mappings":"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"}
package/dist/ai-runner.js CHANGED
@@ -3,6 +3,48 @@ import { getProcessCwd, nodeBunFactory, } from '@gobing-ai/ts-runtime';
3
3
  import { getAgentShim } from './agents/shims.js';
4
4
  import { buildIdentityPreamble } from './identity.js';
5
5
  import { translateSlashCommand } from './slash-command.js';
6
+ /**
7
+ * Public environment-variable contract for agent run correlation.
8
+ *
9
+ * When `AgentRunOptions.correlation` is supplied, `AiRunner` forwards these
10
+ * identifiers into the agent subprocess environment via `ProcessOptions.env`.
11
+ * execa's default `extendEnv: true` merges them with the parent process
12
+ * environment, so they are additive — and because environment inheritance is
13
+ * transitive, every descendant of the run inherits the same values.
14
+ *
15
+ * Nesting semantics: **one id per run, shared by all descendants.** Depth is
16
+ * not observable. The consumer's question is "am I inside a run?", which the
17
+ * presence of `SPUR_RUN_ID` answers exactly; a depth counter was rejected as
18
+ * contract with no current consumer (see task 0056 Design).
19
+ *
20
+ * Prefix choice: **`SPUR_`**. The first consumer (Spur's `SessionStart`
21
+ * hook) already reads `SPUR_AGENT` / `SPUR_MODEL` from this environment, so a
22
+ * single vocabulary in one resolver beats a vendor-neutral prefix that forces
23
+ * that resolver to learn a second one. The prefix is a stable public contract;
24
+ * these names cannot be renamed in lockstep with consumers.
25
+ *
26
+ * Only correlation identifiers are forwarded — never tokens, keys, prompts, or
27
+ * user content.
28
+ */
29
+ export const AGENT_RUN_ID_ENV = 'SPUR_RUN_ID';
30
+ /** Execution-id leg of the correlation env contract (see block comment above). */
31
+ export const AGENT_EXECUTION_ID_ENV = 'SPUR_EXECUTION_ID';
32
+ /** Optional action-id leg of the correlation env contract (see block comment above). */
33
+ export const AGENT_ACTION_ID_ENV = 'SPUR_ACTION_ID';
34
+ /**
35
+ * Build the correlation environment for the agent subprocess. Returns
36
+ * `undefined` when there is no correlation, so the `env` key is omitted
37
+ * entirely and the spawn options stay byte-identical for existing callers.
38
+ *
39
+ * Internal: callers go through `AiRunner.invoke`, which guards the absent case.
40
+ */
41
+ function buildCorrelationEnv(correlation) {
42
+ return {
43
+ [AGENT_RUN_ID_ENV]: correlation.runId,
44
+ [AGENT_EXECUTION_ID_ENV]: correlation.executionId,
45
+ ...(correlation.actionId !== undefined ? { [AGENT_ACTION_ID_ENV]: correlation.actionId } : {}),
46
+ };
47
+ }
6
48
  /** Dispatches coding-agent CLI commands through pure command shims. */
7
49
  export class AiRunner {
8
50
  processExecutor;
@@ -77,6 +119,7 @@ export class AiRunner {
77
119
  label,
78
120
  ...(options.correlation !== undefined ? { correlation: options.correlation } : {}),
79
121
  });
122
+ const correlationEnv = options.correlation === undefined ? undefined : buildCorrelationEnv(options.correlation);
80
123
  const result = await this.processExecutor.run({
81
124
  command: command.command,
82
125
  args: command.args,
@@ -85,6 +128,7 @@ export class AiRunner {
85
128
  forceBuffered,
86
129
  cwd: options.cwd ?? this.defaultCwd,
87
130
  timeout: options.timeout ?? this.defaultTimeout,
131
+ ...(correlationEnv !== undefined ? { env: correlationEnv } : {}),
88
132
  ...(options.signal !== undefined ? { signal: options.signal } : {}),
89
133
  ...(options.onOutput !== undefined ? { onOutput: options.onOutput } : {}),
90
134
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gobing-ai/ts-ai-runner",
3
- "version": "0.4.13",
3
+ "version": "0.4.15",
4
4
  "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
5
5
  "keywords": [
6
6
  "typescript",
@@ -47,12 +47,12 @@
47
47
  "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-ai-runner-v<version> && git push --tags' && exit 1"
48
48
  },
49
49
  "dependencies": {
50
- "@gobing-ai/ts-infra": "^0.4.13",
51
- "@gobing-ai/ts-runtime": "^0.4.13"
50
+ "@gobing-ai/ts-infra": "^0.4.15",
51
+ "@gobing-ai/ts-runtime": "^0.4.15"
52
52
  },
53
53
  "devDependencies": {
54
54
  "@types/bun": "1.3.14",
55
- "@gobing-ai/ts-db": "^0.4.13"
55
+ "@gobing-ai/ts-db": "^0.4.15"
56
56
  },
57
57
  "publishConfig": {
58
58
  "access": "public"
package/src/ai-runner.ts CHANGED
@@ -46,6 +46,49 @@ export interface AgentRunCorrelation {
46
46
  readonly executionId: string;
47
47
  readonly actionId?: string;
48
48
  }
49
+ /**
50
+ * Public environment-variable contract for agent run correlation.
51
+ *
52
+ * When `AgentRunOptions.correlation` is supplied, `AiRunner` forwards these
53
+ * identifiers into the agent subprocess environment via `ProcessOptions.env`.
54
+ * execa's default `extendEnv: true` merges them with the parent process
55
+ * environment, so they are additive — and because environment inheritance is
56
+ * transitive, every descendant of the run inherits the same values.
57
+ *
58
+ * Nesting semantics: **one id per run, shared by all descendants.** Depth is
59
+ * not observable. The consumer's question is "am I inside a run?", which the
60
+ * presence of `SPUR_RUN_ID` answers exactly; a depth counter was rejected as
61
+ * contract with no current consumer (see task 0056 Design).
62
+ *
63
+ * Prefix choice: **`SPUR_`**. The first consumer (Spur's `SessionStart`
64
+ * hook) already reads `SPUR_AGENT` / `SPUR_MODEL` from this environment, so a
65
+ * single vocabulary in one resolver beats a vendor-neutral prefix that forces
66
+ * that resolver to learn a second one. The prefix is a stable public contract;
67
+ * these names cannot be renamed in lockstep with consumers.
68
+ *
69
+ * Only correlation identifiers are forwarded — never tokens, keys, prompts, or
70
+ * user content.
71
+ */
72
+ export const AGENT_RUN_ID_ENV = 'SPUR_RUN_ID';
73
+ /** Execution-id leg of the correlation env contract (see block comment above). */
74
+ export const AGENT_EXECUTION_ID_ENV = 'SPUR_EXECUTION_ID';
75
+ /** Optional action-id leg of the correlation env contract (see block comment above). */
76
+ export const AGENT_ACTION_ID_ENV = 'SPUR_ACTION_ID';
77
+
78
+ /**
79
+ * Build the correlation environment for the agent subprocess. Returns
80
+ * `undefined` when there is no correlation, so the `env` key is omitted
81
+ * entirely and the spawn options stay byte-identical for existing callers.
82
+ *
83
+ * Internal: callers go through `AiRunner.invoke`, which guards the absent case.
84
+ */
85
+ function buildCorrelationEnv(correlation: AgentRunCorrelation): Record<string, string> {
86
+ return {
87
+ [AGENT_RUN_ID_ENV]: correlation.runId,
88
+ [AGENT_EXECUTION_ID_ENV]: correlation.executionId,
89
+ ...(correlation.actionId !== undefined ? { [AGENT_ACTION_ID_ENV]: correlation.actionId } : {}),
90
+ };
91
+ }
49
92
 
50
93
  /** Constructor options for AiRunner. */
51
94
  export interface AiRunnerOptions {
@@ -170,6 +213,7 @@ export class AiRunner {
170
213
  label,
171
214
  ...(options.correlation !== undefined ? { correlation: options.correlation } : {}),
172
215
  });
216
+ const correlationEnv = options.correlation === undefined ? undefined : buildCorrelationEnv(options.correlation);
173
217
  const result: ProcessResult = await this.processExecutor.run({
174
218
  command: command.command,
175
219
  args: command.args,
@@ -178,6 +222,7 @@ export class AiRunner {
178
222
  forceBuffered,
179
223
  cwd: options.cwd ?? this.defaultCwd,
180
224
  timeout: options.timeout ?? this.defaultTimeout,
225
+ ...(correlationEnv !== undefined ? { env: correlationEnv } : {}),
181
226
  ...(options.signal !== undefined ? { signal: options.signal } : {}),
182
227
  ...(options.onOutput !== undefined ? { onOutput: options.onOutput } : {}),
183
228
  });