@terreno/ai 57.10.1 → 57.12.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 (66) hide show
  1. package/dist/aiApp.d.ts +5 -0
  2. package/dist/aiApp.js +4 -2
  3. package/dist/harness/commit.d.ts +17 -1
  4. package/dist/harness/commit.js +86 -2
  5. package/dist/harness/errors.d.ts +6 -0
  6. package/dist/harness/errors.js +6 -0
  7. package/dist/harness/harness.d.ts +2 -2
  8. package/dist/harness/harness.js +4 -2
  9. package/dist/harness/models/harnessTask.js +5 -0
  10. package/dist/harness/routes/approvals.js +2 -2
  11. package/dist/harness/routes/conversations.js +1 -1
  12. package/dist/harness/routes/tasks.js +85 -3
  13. package/dist/harness/runners/inProcessRunner.d.ts +11 -4
  14. package/dist/harness/runners/inProcessRunner.js +44 -13
  15. package/dist/harness/runners/jobsRunner.d.ts +62 -0
  16. package/dist/harness/runners/jobsRunner.js +212 -0
  17. package/dist/harness/runtime.d.ts +20 -2
  18. package/dist/harness/runtime.js +91 -32
  19. package/dist/harness/subagent.d.ts +17 -2
  20. package/dist/harness/subagent.js +26 -2
  21. package/dist/index.d.ts +1 -1
  22. package/dist/index.js +3 -2
  23. package/dist/models/project.d.ts +13 -0
  24. package/dist/models/project.js +32 -2
  25. package/dist/observability/local/models/obsTrace.js +16 -2
  26. package/dist/observability/local/traceStore.d.ts +5 -0
  27. package/dist/observability/local/traceStore.js +5 -0
  28. package/dist/observability/routes/traces.js +2 -0
  29. package/dist/routes/projects.js +3 -3
  30. package/dist/service/chatTurn.js +1 -1
  31. package/dist/types/harness.d.ts +47 -3
  32. package/dist/types/observability.d.ts +3 -0
  33. package/package.json +65 -6
  34. package/src/aiApp.test.ts +15 -0
  35. package/src/aiApp.ts +9 -1
  36. package/src/harness/commit.ts +103 -1
  37. package/src/harness/concurrency.test.ts +155 -0
  38. package/src/harness/errors.ts +6 -0
  39. package/src/harness/events.test.ts +17 -5
  40. package/src/harness/harness.ts +14 -3
  41. package/src/harness/models/harnessTask.ts +5 -0
  42. package/src/harness/ownership.test.ts +9 -9
  43. package/src/harness/recovery.test.ts +2 -7
  44. package/src/harness/routes/approvals.ts +2 -2
  45. package/src/harness/routes/conversations.ts +1 -1
  46. package/src/harness/routes/tasks.test.ts +34 -0
  47. package/src/harness/routes/tasks.ts +98 -3
  48. package/src/harness/runners/inProcessRunner.test.ts +128 -0
  49. package/src/harness/runners/inProcessRunner.ts +54 -14
  50. package/src/harness/runners/jobsRunner.test.ts +709 -0
  51. package/src/harness/runners/jobsRunner.ts +252 -0
  52. package/src/harness/runtime.ts +125 -30
  53. package/src/harness/subagent.test.ts +124 -3
  54. package/src/harness/subagent.ts +43 -1
  55. package/src/index.ts +1 -1
  56. package/src/isolated/lazyProjectModel.isolated.ts +25 -0
  57. package/src/models/project.ts +31 -1
  58. package/src/observability/local/models/obsTrace.ts +22 -5
  59. package/src/observability/local/traceStore.test.ts +7 -0
  60. package/src/observability/local/traceStore.ts +12 -0
  61. package/src/observability/routes/traces.test.ts +15 -0
  62. package/src/observability/routes/traces.ts +2 -0
  63. package/src/routes/projects.ts +4 -4
  64. package/src/service/chatTurn.ts +2 -2
  65. package/src/types/harness.ts +56 -3
  66. package/src/types/observability.ts +3 -0
@@ -0,0 +1,212 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.JobsRunner = exports.HARNESS_PHASE_JOB_NAME = void 0;
4
+ const node_crypto_1 = require("node:crypto");
5
+ const node_os_1 = require("node:os");
6
+ const api_1 = require("@terreno/api");
7
+ const jobs_1 = require("@terreno/jobs");
8
+ const luxon_1 = require("luxon");
9
+ const errors_1 = require("../errors");
10
+ /** Job that runs one phase of one harness task. */
11
+ exports.HARNESS_PHASE_JOB_NAME = "terreno.harness.phase";
12
+ /** Job statuses that still lead to a handler run; any other status will never claim. */
13
+ const IN_FLIGHT_JOB_STATUSES = new Set(["pending", "running", "scheduled"]);
14
+ const parsePayload = (payload) => {
15
+ const taskId = payload?.taskId;
16
+ if (typeof taskId !== "string" || !taskId) {
17
+ throw (0, errors_1.harnessError)({
18
+ detail: `${exports.HARNESS_PHASE_JOB_NAME} payload needs a taskId string`,
19
+ kind: "invalidRequest",
20
+ });
21
+ }
22
+ return { taskId };
23
+ };
24
+ /** `taskId:phase:attempt:claims` — one key per runnable visit of a phase. */
25
+ const phaseJobKey = (task) => `${task.taskId}:${task.phase}:${task.attempt}:${task.claims}`;
26
+ /**
27
+ * Executes harness phases as `@terreno/jobs` jobs so any number of instances share the
28
+ * work. Every instance runs a dispatcher that enqueues one `terreno.harness.phase` job per
29
+ * runnable task (deduplicated by idempotency key) and sweeps expired task leases. The job
30
+ * handler claims its task under a fenced lease, runs one phase while heartbeating, and
31
+ * hands a still-running task back as `pending` for the next job. The task lease, not the
32
+ * job lock, decides who may commit: a duplicate or late job finds the task claimed and
33
+ * does nothing, and a stale lease holder's commit is rejected.
34
+ */
35
+ class JobsRunner {
36
+ context;
37
+ dispatchBatchSize;
38
+ hasPendingWake = false;
39
+ inFlight = new Set();
40
+ isStopping = false;
41
+ lease;
42
+ loop;
43
+ nextSweepAt = luxon_1.DateTime.fromMillis(0);
44
+ pollIntervalMs;
45
+ wakeSleeper;
46
+ constructor(options) {
47
+ const duration = luxon_1.Duration.fromDurationLike(options.leaseDuration ?? { seconds: 30 });
48
+ const heartbeat = luxon_1.Duration.fromDurationLike(options.heartbeatInterval ?? { seconds: 10 });
49
+ if (heartbeat.toMillis() <= 0 || heartbeat.toMillis() >= duration.toMillis()) {
50
+ throw (0, errors_1.harnessError)({
51
+ detail: "JobsRunner heartbeatInterval must be positive and shorter than leaseDuration",
52
+ kind: "configInvalid",
53
+ });
54
+ }
55
+ this.lease = {
56
+ duration,
57
+ heartbeat,
58
+ owner: options.ownerId ?? `${(0, node_os_1.hostname)()}:${process.pid}:${(0, node_crypto_1.randomUUID)()}`,
59
+ };
60
+ this.pollIntervalMs = luxon_1.Duration.fromDurationLike(options.pollInterval ?? { milliseconds: 500 }).toMillis();
61
+ const dispatchBatchSize = options.dispatchBatchSize ?? 100;
62
+ if (!Number.isInteger(dispatchBatchSize) || dispatchBatchSize < 1) {
63
+ throw (0, errors_1.harnessError)({
64
+ detail: "JobsRunner dispatchBatchSize must be a positive integer",
65
+ kind: "configInvalid",
66
+ });
67
+ }
68
+ this.dispatchBatchSize = dispatchBatchSize;
69
+ options.jobs.define(exports.HARNESS_PHASE_JOB_NAME, {
70
+ handler: (payload) => this.runPhaseJob(payload),
71
+ });
72
+ }
73
+ /** Id written into every task lease this runner holds. */
74
+ get ownerId() {
75
+ return this.lease.owner;
76
+ }
77
+ async start(context) {
78
+ if (this.loop !== undefined) {
79
+ throw (0, errors_1.harnessError)({ detail: "JobsRunner is already started", kind: "alreadyStarted" });
80
+ }
81
+ if (!(0, jobs_1.tryGetJobsService)()) {
82
+ throw (0, errors_1.harnessError)({
83
+ detail: "JobsRunner needs a registered JobsApp: register it and build the app before harness.start()",
84
+ kind: "configInvalid",
85
+ });
86
+ }
87
+ this.context = context;
88
+ this.isStopping = false;
89
+ this.nextSweepAt = luxon_1.DateTime.fromMillis(0);
90
+ this.loop = this.dispatchLoop();
91
+ }
92
+ /** Stop dispatching, then wait for every phase this instance is running. */
93
+ async stop() {
94
+ if (this.loop === undefined) {
95
+ return;
96
+ }
97
+ this.isStopping = true;
98
+ this.wake();
99
+ await this.loop;
100
+ await Promise.allSettled([...this.inFlight]);
101
+ this.loop = undefined;
102
+ this.context = undefined;
103
+ }
104
+ /** Dispatch now instead of after the rest of the idle sleep. */
105
+ wake() {
106
+ if (this.wakeSleeper) {
107
+ this.wakeSleeper();
108
+ return;
109
+ }
110
+ this.hasPendingWake = true;
111
+ }
112
+ /** Job handler: claim the task, run one phase, and hand it back if it still runs. */
113
+ async runPhaseJob(payload) {
114
+ const { taskId } = parsePayload(payload);
115
+ // Tracked from before the claim, so stop() also waits for a claim in flight.
116
+ const job = this.claimAndRunPhase(taskId);
117
+ this.inFlight.add(job);
118
+ try {
119
+ await job;
120
+ }
121
+ finally {
122
+ this.inFlight.delete(job);
123
+ }
124
+ }
125
+ async claimAndRunPhase(taskId) {
126
+ const context = this.context;
127
+ if (!context || this.isStopping) {
128
+ // Throwing makes the jobs worker retry later, on this instance or another one.
129
+ throw (0, errors_1.harnessError)({
130
+ detail: `JobsRunner is not running; task ${taskId} stays runnable`,
131
+ kind: "runnerStopped",
132
+ });
133
+ }
134
+ const task = await context.claimTask(taskId, this.lease);
135
+ if (!task) {
136
+ // Another job claimed it first, or it stopped being runnable since dispatch.
137
+ return;
138
+ }
139
+ await context.runTask(task, this.lease, { maxPhases: 1 });
140
+ // The next phase (or a retry that is already due) can be dispatched right away.
141
+ this.wake();
142
+ }
143
+ async dispatchLoop() {
144
+ while (!this.isStopping && this.context) {
145
+ await this.tick(this.context);
146
+ if (!this.isStopping) {
147
+ await this.sleep(this.pollIntervalMs);
148
+ }
149
+ }
150
+ }
151
+ /** Recover expired leases once per heartbeat, then enqueue a job per runnable task. */
152
+ async tick(context) {
153
+ try {
154
+ if (luxon_1.DateTime.now() >= this.nextSweepAt) {
155
+ this.nextSweepAt = luxon_1.DateTime.now().plus(this.lease.heartbeat);
156
+ await context.recoverExpired();
157
+ }
158
+ const runnable = await context.listRunnable(this.dispatchBatchSize);
159
+ for (const task of runnable) {
160
+ if (this.isStopping) {
161
+ return;
162
+ }
163
+ await this.dispatch(task);
164
+ }
165
+ }
166
+ catch (error) {
167
+ api_1.logger.error(`JobsRunner dispatch failed: ${(0, errors_1.errorMessage)(error)}`);
168
+ }
169
+ }
170
+ /**
171
+ * Enqueue the job for this runnable visit. When the job with that key already ended
172
+ * without claiming the task (its handler kept failing, or it ran where the task was not
173
+ * runnable), follow or extend the chain `<key>:<endedJobId>` until a job is in flight, so
174
+ * the task is not stranded. A newly created job is always in flight, so this ends.
175
+ */
176
+ async dispatch(task) {
177
+ const jobs = (0, jobs_1.tryGetJobsService)();
178
+ if (!jobs) {
179
+ throw (0, errors_1.harnessError)({ detail: "JobsApp is no longer registered", kind: "configInvalid" });
180
+ }
181
+ let idempotencyKey = phaseJobKey(task);
182
+ for (;;) {
183
+ const job = await jobs.enqueue({
184
+ idempotencyKey,
185
+ name: exports.HARNESS_PHASE_JOB_NAME,
186
+ payload: { taskId: task.taskId },
187
+ });
188
+ if (IN_FLIGHT_JOB_STATUSES.has(job.status)) {
189
+ return;
190
+ }
191
+ idempotencyKey = `${phaseJobKey(task)}:${job._id}`;
192
+ }
193
+ }
194
+ sleep(ms) {
195
+ if (this.hasPendingWake) {
196
+ this.hasPendingWake = false;
197
+ return Promise.resolve();
198
+ }
199
+ return new Promise((resolve) => {
200
+ const timer = setTimeout(() => {
201
+ this.wakeSleeper = undefined;
202
+ resolve();
203
+ }, ms);
204
+ this.wakeSleeper = () => {
205
+ clearTimeout(timer);
206
+ this.wakeSleeper = undefined;
207
+ resolve();
208
+ };
209
+ });
210
+ }
211
+ }
212
+ exports.JobsRunner = JobsRunner;
@@ -1,4 +1,4 @@
1
- import type { HarnessLeaseSettings, HarnessTaskDefinition, HarnessTaskDocument } from "../types/harness";
1
+ import type { HarnessLeaseSettings, HarnessRunnableTask, HarnessTaskDefinition, HarnessTaskDocument } from "../types/harness";
2
2
  import { type HarnessModels } from "./commit";
3
3
  import { type HarnessEngine } from "./ownership";
4
4
  /**
@@ -10,6 +10,22 @@ export declare const claimNextTask: ({ definitions, lease, models, }: {
10
10
  lease: HarnessLeaseSettings;
11
11
  models: HarnessModels;
12
12
  }) => Promise<HarnessTaskDocument | null>;
13
+ /**
14
+ * Claim one task by id under the same rules as `claimNextTask`. Null when the task is not
15
+ * runnable now: unknown, not due, already claimed by another runner, terminal, or aborting.
16
+ */
17
+ export declare const claimTaskById: ({ definitions, lease, models, taskId, }: {
18
+ definitions: Map<string, HarnessTaskDefinition>;
19
+ lease: HarnessLeaseSettings;
20
+ models: HarnessModels;
21
+ taskId: string;
22
+ }) => Promise<HarnessTaskDocument | null>;
23
+ /** Oldest runnable, registered tasks first, at most `limit`, without claiming them. */
24
+ export declare const listRunnableTasks: ({ definitions, limit, models, }: {
25
+ definitions: Map<string, HarnessTaskDefinition>;
26
+ limit: number;
27
+ models: HarnessModels;
28
+ }) => Promise<HarnessRunnableTask[]>;
13
29
  /**
14
30
  * Find `running` tasks whose lease expired (their runner died or froze mid-phase) and
15
31
  * resolve each by its current phase's `replay`: `safe` goes back to `pending` at the same
@@ -27,8 +43,10 @@ export declare const recoverExpiredTasks: (engine: HarnessEngine) => Promise<num
27
43
  * was lost, the task is left at its last checkpoint and expired-lease recovery decides
28
44
  * what happens next. A terminal task re-checks the task that owns it.
29
45
  */
30
- export declare const runClaimedTask: ({ engine, lease, task, }: {
46
+ export declare const runClaimedTask: ({ engine, lease, maxPhases, task, }: {
31
47
  engine: HarnessEngine;
32
48
  lease: HarnessLeaseSettings;
49
+ /** Hand the task back as `pending` once this many phases committed and it still runs. */
50
+ maxPhases?: number;
33
51
  task: HarnessTaskDocument;
34
52
  }) => Promise<void>;
@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.runClaimedTask = exports.recoverExpiredTasks = exports.claimNextTask = void 0;
6
+ exports.runClaimedTask = exports.recoverExpiredTasks = exports.listRunnableTasks = exports.claimTaskById = exports.claimNextTask = void 0;
7
7
  const api_1 = require("@terreno/api");
8
8
  const luxon_1 = require("luxon");
9
9
  const mongoose_1 = __importDefault(require("mongoose"));
@@ -42,6 +42,37 @@ const assertValidNext = (definition, next) => {
42
42
  const registeredFilter = (definitions) => {
43
43
  return [...definitions.values()].map(({ name, version }) => ({ name, version }));
44
44
  };
45
+ /**
46
+ * Mongo filter for a registered task a runner may claim now: `pending` and due, or
47
+ * `waiting` on an event or sleep whose `timeoutAt` passed, and not being aborted.
48
+ */
49
+ const runnableTaskFilter = (definitions, now) => ({
50
+ $and: [
51
+ { $or: registeredFilter(definitions) },
52
+ {
53
+ $or: [
54
+ {
55
+ $or: [{ runAt: { $exists: false } }, { runAt: null }, { runAt: { $lte: now.toJSDate() } }],
56
+ status: harness_1.HARNESS_TASK_STATUSES.pending,
57
+ },
58
+ // An event wait or sleep whose timeout passed resumes like a due retry.
59
+ {
60
+ status: harness_1.HARNESS_TASK_STATUSES.waiting,
61
+ "waiting.kind": { $in: [harness_1.HARNESS_WAIT_KINDS.event, harness_1.HARNESS_WAIT_KINDS.sleep] },
62
+ "waiting.timeoutAt": { $lte: now.toJSDate() },
63
+ },
64
+ ],
65
+ },
66
+ ],
67
+ // A task being aborted never starts another run.
68
+ "abortRequested.at": { $exists: false },
69
+ });
70
+ /** Move a runnable task to `running` under a fresh lease (owner, fencing token, expiry). */
71
+ const claimUpdate = (lease) => ({
72
+ $inc: { claims: 1 },
73
+ $set: { lease: (0, commit_1.newTaskLease)(lease), status: harness_1.HARNESS_TASK_STATUSES.running },
74
+ $unset: { waiting: 1 },
75
+ });
45
76
  /**
46
77
  * Atomically move the oldest runnable, registered task (`pending` and due, or `waiting` on
47
78
  * an event or sleep whose `timeoutAt` passed) to `running` and give it a fresh lease (owner, fencing token, expiry) for the phase about to start.
@@ -50,34 +81,50 @@ const claimNextTask = async ({ definitions, lease, models, }) => {
50
81
  if (definitions.size === 0) {
51
82
  return null;
52
83
  }
53
- const registered = registeredFilter(definitions);
54
- const now = luxon_1.DateTime.now().toJSDate();
55
- return models.task.findOneAndUpdate({
56
- $and: [
57
- { $or: registered },
58
- {
59
- $or: [
60
- {
61
- $or: [{ runAt: { $exists: false } }, { runAt: null }, { runAt: { $lte: now } }],
62
- status: harness_1.HARNESS_TASK_STATUSES.pending,
63
- },
64
- // An event wait or sleep whose timeout passed resumes like a due retry.
65
- {
66
- status: harness_1.HARNESS_TASK_STATUSES.waiting,
67
- "waiting.kind": { $in: [harness_1.HARNESS_WAIT_KINDS.event, harness_1.HARNESS_WAIT_KINDS.sleep] },
68
- "waiting.timeoutAt": { $lte: now },
69
- },
70
- ],
71
- },
72
- ],
73
- // A task being aborted never starts another run.
74
- "abortRequested.at": { $exists: false },
75
- }, {
76
- $set: { lease: (0, commit_1.newTaskLease)(lease), status: harness_1.HARNESS_TASK_STATUSES.running },
77
- $unset: { waiting: 1 },
78
- }, { returnDocument: "after", sort: { created: 1 } });
84
+ return models.task.findOneAndUpdate(runnableTaskFilter(definitions, luxon_1.DateTime.now()), claimUpdate(lease), { returnDocument: "after", sort: { created: 1 } });
79
85
  };
80
86
  exports.claimNextTask = claimNextTask;
87
+ /**
88
+ * Claim one task by id under the same rules as `claimNextTask`. Null when the task is not
89
+ * runnable now: unknown, not due, already claimed by another runner, terminal, or aborting.
90
+ */
91
+ const claimTaskById = async ({ definitions, lease, models, taskId, }) => {
92
+ if (definitions.size === 0 || !mongoose_1.default.isValidObjectId(taskId)) {
93
+ return null;
94
+ }
95
+ return models.task.findOneAndUpdate({ ...runnableTaskFilter(definitions, luxon_1.DateTime.now()), _id: toObjectId(taskId) }, claimUpdate(lease), { returnDocument: "after" });
96
+ };
97
+ exports.claimTaskById = claimTaskById;
98
+ /** Oldest runnable, registered tasks first, at most `limit`, without claiming them. */
99
+ const listRunnableTasks = async ({ definitions, limit, models, }) => {
100
+ if (definitions.size === 0) {
101
+ return [];
102
+ }
103
+ const tasks = await models.task
104
+ .find(runnableTaskFilter(definitions, luxon_1.DateTime.now()))
105
+ .select({ attempt: 1, claims: 1, phase: 1 })
106
+ .sort({ created: 1 })
107
+ .limit(limit);
108
+ return tasks.map((task) => ({
109
+ attempt: task.attempt ?? 0,
110
+ claims: task.claims ?? 0,
111
+ phase: task.phase,
112
+ taskId: String(task._id),
113
+ }));
114
+ };
115
+ exports.listRunnableTasks = listRunnableTasks;
116
+ /**
117
+ * Give a task that is still `running` under `task`'s lease back to the runners as
118
+ * `pending` at its current checkpoint. False when the lease moved on (aborted, recovered).
119
+ */
120
+ const releaseTask = async (models, task) => {
121
+ const result = await models.task.updateOne({
122
+ _id: task._id,
123
+ "lease.token": task.lease?.token ?? null,
124
+ status: harness_1.HARNESS_TASK_STATUSES.running,
125
+ }, { $set: { status: harness_1.HARNESS_TASK_STATUSES.pending }, $unset: { lease: 1 } });
126
+ return result.modifiedCount > 0;
127
+ };
81
128
  /**
82
129
  * Find `running` tasks whose lease expired (their runner died or froze mid-phase) and
83
130
  * resolve each by its current phase's `replay`: `safe` goes back to `pending` at the same
@@ -140,7 +187,7 @@ const interruptionAction = (definition, phase) => {
140
187
  * was lost, the task is left at its last checkpoint and expired-lease recovery decides
141
188
  * what happens next. A terminal task re-checks the task that owns it.
142
189
  */
143
- const runClaimedTask = async ({ engine, lease, task, }) => {
190
+ const runClaimedTask = async ({ engine, lease, maxPhases, task, }) => {
144
191
  const definition = engine.definitions.get((0, defineTask_1.taskDefinitionKey)(task));
145
192
  if (!definition) {
146
193
  throw (0, errors_1.harnessError)({
@@ -153,14 +200,20 @@ const runClaimedTask = async ({ engine, lease, task, }) => {
153
200
  engine.controllers.set(taskId, controller);
154
201
  try {
155
202
  let current = task;
156
- let isFirstPhase = true;
203
+ let phasesRun = 0;
157
204
  while (current.status === harness_1.HARNESS_TASK_STATUSES.running && !controller.signal.aborted) {
205
+ if (maxPhases !== undefined && phasesRun >= maxPhases) {
206
+ if (!(await releaseTask(engine.models, current))) {
207
+ api_1.logger.info(`Harness task ${taskId} lost its lease before hand-off; stopping`);
208
+ }
209
+ return;
210
+ }
158
211
  // An abort from another process may have fenced the task since the last commit.
159
- if (!isFirstPhase && !(await holdsLease(engine.models, current))) {
212
+ if (phasesRun > 0 && !(await holdsLease(engine.models, current))) {
160
213
  api_1.logger.info(`Harness task ${taskId} lost its lease between phases; stopping`);
161
214
  return;
162
215
  }
163
- isFirstPhase = false;
216
+ phasesRun += 1;
164
217
  const result = await runPhase({ controller, definition, engine, lease, task: current });
165
218
  if (!result) {
166
219
  return;
@@ -403,16 +456,22 @@ const runPhase = async ({ controller, definition, engine, lease, task, }) => {
403
456
  throw new definitionError_1.HarnessDefinitionError(`${definition.key}: rt.runAgent output for "${agent.name}" cannot be expressed as JSON Schema: ${(0, errors_1.errorMessage)(error)}`);
404
457
  }
405
458
  }
459
+ const { instructions, prompts } = (0, subagent_1.subagentPrompts)({
460
+ instructions: options.instructions,
461
+ prompts: options.prompts,
462
+ where: `${definition.key}: rt.runAgent`,
463
+ });
406
464
  const { conversationId, turnTask } = await (0, subagent_1.startSubagentTurn)({
407
465
  agent,
408
466
  callIndex,
409
467
  content,
410
468
  extensions: engine.extensions,
411
- instructions: options.instructions,
469
+ instructions,
412
470
  lease,
413
471
  models,
414
472
  outputSchema,
415
473
  parent: task,
474
+ prompts,
416
475
  turn,
417
476
  });
418
477
  engine.wake();
@@ -1,5 +1,5 @@
1
1
  import type { z } from "@terreno/api";
2
- import type { HarnessAgentDefinition, HarnessChildOutcome, HarnessExtensionDefinition, HarnessLeaseSettings, HarnessTaskDefinition, HarnessTaskDocument } from "../types/harness";
2
+ import type { HarnessAgentDefinition, HarnessChildOutcome, HarnessExtensionDefinition, HarnessLeaseSettings, HarnessPromptInstructions, HarnessPromptRef, HarnessTaskDefinition, HarnessTaskDocument } from "../types/harness";
3
3
  import { type HarnessModels } from "./commit";
4
4
  /** A subagent run by `rt.runAgent` did not produce a usable answer. */
5
5
  export declare class HarnessSubagentError extends Error {
@@ -17,6 +17,19 @@ export declare class HarnessSubagentError extends Error {
17
17
  }
18
18
  /** The subagent's user message: strings as-is, anything else as JSON. */
19
19
  export declare const subagentContent: (input: unknown) => string | undefined;
20
+ /**
21
+ * Split `rt.runAgent`'s instructions into the text the agent runs with and the prompt
22
+ * versions to record on the trace. A registry prompt passed as `instructions` is used by
23
+ * its `body` and recorded alongside `prompts`.
24
+ */
25
+ export declare const subagentPrompts: ({ instructions, prompts, where, }: {
26
+ instructions?: HarnessPromptInstructions | string;
27
+ prompts?: HarnessPromptRef[];
28
+ where: string;
29
+ }) => {
30
+ instructions?: string;
31
+ prompts: HarnessPromptRef[];
32
+ };
20
33
  /**
21
34
  * Serialize `schema` as JSON Schema with the AI SDK's own converter, so the turn requests
22
35
  * exactly the structure `Output.object` would. Stored as a string: JSON Schema keys such
@@ -28,7 +41,7 @@ export declare const serializeOutputSchema: (schema: z.ZodType) => Promise<strin
28
41
  * `parent` with an `AGENT` span named after the agent) in one transaction. A re-run of
29
42
  * the same phase attempt finds the turn created first, and with it the same conversation.
30
43
  */
31
- export declare const startSubagentTurn: ({ agent, callIndex, content, extensions, instructions, lease, models, outputSchema, parent, turn, }: {
44
+ export declare const startSubagentTurn: ({ agent, callIndex, content, extensions, instructions, lease, models, outputSchema, parent, prompts, turn, }: {
32
45
  agent: HarnessAgentDefinition;
33
46
  callIndex: number;
34
47
  content: string;
@@ -39,6 +52,8 @@ export declare const startSubagentTurn: ({ agent, callIndex, content, extensions
39
52
  models: HarnessModels;
40
53
  outputSchema?: string;
41
54
  parent: HarnessTaskDocument;
55
+ /** Prompt versions recorded on the parent's trace with the turn. */
56
+ prompts?: HarnessPromptRef[];
42
57
  turn: HarnessTaskDefinition;
43
58
  }) => Promise<{
44
59
  conversationId: string;
@@ -3,12 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.subagentResult = exports.startSubagentTurn = exports.serializeOutputSchema = exports.subagentContent = exports.HarnessSubagentError = void 0;
6
+ exports.subagentResult = exports.startSubagentTurn = exports.serializeOutputSchema = exports.subagentPrompts = exports.subagentContent = exports.HarnessSubagentError = void 0;
7
7
  const ai_1 = require("ai");
8
8
  const mongoose_1 = __importDefault(require("mongoose"));
9
9
  const harness_1 = require("../types/harness");
10
10
  const commit_1 = require("./commit");
11
11
  const conversation_1 = require("./conversation");
12
+ const definitionError_1 = require("./definitionError");
13
+ const errors_1 = require("./errors");
12
14
  const events_1 = require("./events");
13
15
  /** A subagent run by `rt.runAgent` did not produce a usable answer. */
14
16
  class HarnessSubagentError extends Error {
@@ -38,6 +40,27 @@ const subagentContent = (input) => {
38
40
  return JSON.stringify(input);
39
41
  };
40
42
  exports.subagentContent = subagentContent;
43
+ /**
44
+ * Split `rt.runAgent`'s instructions into the text the agent runs with and the prompt
45
+ * versions to record on the trace. A registry prompt passed as `instructions` is used by
46
+ * its `body` and recorded alongside `prompts`.
47
+ */
48
+ const subagentPrompts = ({ instructions, prompts, where, }) => {
49
+ const prompt = instructions !== undefined && typeof instructions !== "string" ? instructions : undefined;
50
+ if (prompt && typeof prompt.body !== "string") {
51
+ throw new definitionError_1.HarnessDefinitionError(`${where} instructions prompt needs a string body`);
52
+ }
53
+ try {
54
+ return {
55
+ instructions: prompt ? prompt.body : instructions,
56
+ prompts: (0, commit_1.tracePromptRefs)(prompt ? [prompt, ...(prompts ?? [])] : prompts),
57
+ };
58
+ }
59
+ catch (error) {
60
+ throw new definitionError_1.HarnessDefinitionError(`${where}: ${(0, errors_1.errorMessage)(error)}`);
61
+ }
62
+ };
63
+ exports.subagentPrompts = subagentPrompts;
41
64
  /**
42
65
  * Serialize `schema` as JSON Schema with the AI SDK's own converter, so the turn requests
43
66
  * exactly the structure `Output.object` would. Stored as a string: JSON Schema keys such
@@ -53,7 +76,7 @@ exports.serializeOutputSchema = serializeOutputSchema;
53
76
  * `parent` with an `AGENT` span named after the agent) in one transaction. A re-run of
54
77
  * the same phase attempt finds the turn created first, and with it the same conversation.
55
78
  */
56
- const startSubagentTurn = async ({ agent, callIndex, content, extensions, instructions, lease, models, outputSchema, parent, turn, }) => {
79
+ const startSubagentTurn = async ({ agent, callIndex, content, extensions, instructions, lease, models, outputSchema, parent, prompts = [], turn, }) => {
57
80
  const key = `agent:${callIndex}`;
58
81
  const newConversationId = new mongoose_1.default.Types.ObjectId();
59
82
  const input = { conversationId: String(newConversationId) };
@@ -72,6 +95,7 @@ const startSubagentTurn = async ({ agent, callIndex, content, extensions, instru
72
95
  name: agent.name,
73
96
  },
74
97
  writes: async ({ session, task }) => {
98
+ await (0, commit_1.addTracePrompts)({ models, refs: prompts, session, traceId: parent.traceId });
75
99
  await models.conversation.create([
76
100
  {
77
101
  _id: newConversationId,
package/dist/index.d.ts CHANGED
@@ -16,7 +16,7 @@ export { AIDataset } from "./models/aiDataset";
16
16
  export { AIRequest } from "./models/aiRequest";
17
17
  export { FileAttachment } from "./models/fileAttachment";
18
18
  export { GptHistory } from "./models/gptHistory";
19
- export { Project } from "./models/project";
19
+ export { getProjectModel, Project } from "./models/project";
20
20
  export { AI_OBSERVABILITY_GROUP, observabilityAdminScreens } from "./observability/adminScreens";
21
21
  export { LocalDatasetStore } from "./observability/local/datasetStore";
22
22
  export { LocalEvaluatorStore } from "./observability/local/evaluatorStore";
package/dist/index.js CHANGED
@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
14
  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
15
  };
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
- exports.addAiRequestsExplorerRoutes = exports.validateObservabilityConfig = exports.resolveObservabilityControl = exports.DEFAULT_OBSERVABILITY_CONTROL = exports.isLocalObservabilityPluginOn = exports.buildPlaygroundAiStatus = exports.buildObservabilityStatus = exports.resetObservabilityApp = exports.ObservabilityApp = exports.getObservabilityApp = exports.MemoryTraceSink = exports.MemoryScoreSink = exports.LocalTraceStore = exports.LocalTraceSink = exports.LocalScoreSink = exports.LocalReviewStore = exports.LocalPromptStore = exports.createLocalObservabilityPlugin = exports.createLocalObservabilityBundle = exports.LocalExperimentRunner = exports.LocalEvaluatorStore = exports.LocalDatasetStore = exports.observabilityAdminScreens = exports.AI_OBSERVABILITY_GROUP = exports.Project = exports.GptHistory = exports.FileAttachment = exports.AIRequest = exports.AIDataset = exports.preparePromptForAI = exports.createTelemetryConfig = exports.shutdownTracing = exports.initTracing = exports.invalidatePromptCache = exports.getPrompt = exports.createPrompt = exports.compilePrompt = exports.shutdownLangfuseClient = exports.isLangfuseInitialized = exports.initLangfuseClient = exports.getLangfuseClient = exports.setCached = exports.LangfuseCache = exports.invalidateCache = exports.getCached = exports.LangfuseApp = exports.AiApp = exports.AIAdminApp = exports.Output = exports.jsonSchema = void 0;
18
- exports.verifyVertexModelsEnabled = exports.normalizeVertexModelId = exports.listEnabledVertexModels = exports.isVertexModelAllowed = exports.DEFAULT_VERTEX_LOCATION = exports.createVertexProvider = exports.assertVertexModelsEnabled = exports.TRANSLATION_PROMPT = exports.TITLE_GENERATION_PROMPT = exports.TERRENO_ASKS_SYSTEM_PROMPT = exports.REMIX_PROMPT = exports.JSON_VALUE_SYSTEM_PROMPT = exports.DEFAULT_GPT_MEMORY = exports.CONTENT_SUMMARY_PROMPT = exports.COMPACT_SURFACE_SYSTEM_PROMPT = exports.parseAiJson = exports.normalizeLlmJsonTextForStructuredOutput = exports.MCPService = exports.getMCPTools = exports.normalizeGeminiModelId = exports.listGeminiApiModels = exports.GEMINI_API_BASE_URL = exports.FileStorageService = exports.createAskTools = exports.TemperaturePresets = exports.AIService = exports.registerAiDataset = exports.configureAiDatasets = exports.addProjectRoutes = exports.addMcpRoutes = exports.addGptHistoryRoutes = exports.addGptRoutes = exports.addFileRoutes = void 0;
17
+ exports.validateObservabilityConfig = exports.resolveObservabilityControl = exports.DEFAULT_OBSERVABILITY_CONTROL = exports.isLocalObservabilityPluginOn = exports.buildPlaygroundAiStatus = exports.buildObservabilityStatus = exports.resetObservabilityApp = exports.ObservabilityApp = exports.getObservabilityApp = exports.MemoryTraceSink = exports.MemoryScoreSink = exports.LocalTraceStore = exports.LocalTraceSink = exports.LocalScoreSink = exports.LocalReviewStore = exports.LocalPromptStore = exports.createLocalObservabilityPlugin = exports.createLocalObservabilityBundle = exports.LocalExperimentRunner = exports.LocalEvaluatorStore = exports.LocalDatasetStore = exports.observabilityAdminScreens = exports.AI_OBSERVABILITY_GROUP = exports.Project = exports.getProjectModel = exports.GptHistory = exports.FileAttachment = exports.AIRequest = exports.AIDataset = exports.preparePromptForAI = exports.createTelemetryConfig = exports.shutdownTracing = exports.initTracing = exports.invalidatePromptCache = exports.getPrompt = exports.createPrompt = exports.compilePrompt = exports.shutdownLangfuseClient = exports.isLangfuseInitialized = exports.initLangfuseClient = exports.getLangfuseClient = exports.setCached = exports.LangfuseCache = exports.invalidateCache = exports.getCached = exports.LangfuseApp = exports.AiApp = exports.AIAdminApp = exports.Output = exports.jsonSchema = void 0;
18
+ exports.verifyVertexModelsEnabled = exports.normalizeVertexModelId = exports.listEnabledVertexModels = exports.isVertexModelAllowed = exports.DEFAULT_VERTEX_LOCATION = exports.createVertexProvider = exports.assertVertexModelsEnabled = exports.TRANSLATION_PROMPT = exports.TITLE_GENERATION_PROMPT = exports.TERRENO_ASKS_SYSTEM_PROMPT = exports.REMIX_PROMPT = exports.JSON_VALUE_SYSTEM_PROMPT = exports.DEFAULT_GPT_MEMORY = exports.CONTENT_SUMMARY_PROMPT = exports.COMPACT_SURFACE_SYSTEM_PROMPT = exports.parseAiJson = exports.normalizeLlmJsonTextForStructuredOutput = exports.MCPService = exports.getMCPTools = exports.normalizeGeminiModelId = exports.listGeminiApiModels = exports.GEMINI_API_BASE_URL = exports.FileStorageService = exports.createAskTools = exports.TemperaturePresets = exports.AIService = exports.registerAiDataset = exports.configureAiDatasets = exports.addProjectRoutes = exports.addMcpRoutes = exports.addGptHistoryRoutes = exports.addGptRoutes = exports.addFileRoutes = exports.addAiRequestsExplorerRoutes = void 0;
19
19
  var ai_1 = require("ai");
20
20
  Object.defineProperty(exports, "jsonSchema", { enumerable: true, get: function () { return ai_1.jsonSchema; } });
21
21
  Object.defineProperty(exports, "Output", { enumerable: true, get: function () { return ai_1.Output; } });
@@ -55,6 +55,7 @@ Object.defineProperty(exports, "FileAttachment", { enumerable: true, get: functi
55
55
  var gptHistory_1 = require("./models/gptHistory");
56
56
  Object.defineProperty(exports, "GptHistory", { enumerable: true, get: function () { return gptHistory_1.GptHistory; } });
57
57
  var project_1 = require("./models/project");
58
+ Object.defineProperty(exports, "getProjectModel", { enumerable: true, get: function () { return project_1.getProjectModel; } });
58
59
  Object.defineProperty(exports, "Project", { enumerable: true, get: function () { return project_1.Project; } });
59
60
  var adminScreens_1 = require("./observability/adminScreens");
60
61
  Object.defineProperty(exports, "AI_OBSERVABILITY_GROUP", { enumerable: true, get: function () { return adminScreens_1.AI_OBSERVABILITY_GROUP; } });
@@ -1,2 +1,15 @@
1
1
  import type { ProjectModel } from "../types";
2
+ /**
3
+ * The AI chat `Project` model, registered on first use rather than on import, so an app
4
+ * that imports `@terreno/ai` can own a model named `Project` as long as it does not also
5
+ * use AI projects.
6
+ */
7
+ export declare const getProjectModel: () => ProjectModel;
8
+ /**
9
+ * Lazy stand-in for the `Project` model: every access registers it via `getProjectModel`.
10
+ * Statics, `new Project(...)` and `instanceof Project` work, but the proxy is not the model
11
+ * itself (`Project !== mongoose.models.Project`, `Object.keys(Project)` is empty, and reading
12
+ * `Project.prototype` throws).
13
+ * @deprecated Use `getProjectModel()`.
14
+ */
2
15
  export declare const Project: ProjectModel;
@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.Project = void 0;
6
+ exports.Project = exports.getProjectModel = void 0;
7
7
  const api_1 = require("@terreno/api");
8
8
  const mongoose_1 = __importDefault(require("mongoose"));
9
9
  const memorySchema = new mongoose_1.default.Schema({
@@ -44,4 +44,34 @@ projectSchema.plugin(api_1.findExactlyOne);
44
44
  projectSchema.virtual("ownerId").get(function () {
45
45
  return this.userId;
46
46
  });
47
- exports.Project = mongoose_1.default.model("Project", projectSchema);
47
+ let projectModel;
48
+ /**
49
+ * The AI chat `Project` model, registered on first use rather than on import, so an app
50
+ * that imports `@terreno/ai` can own a model named `Project` as long as it does not also
51
+ * use AI projects.
52
+ */
53
+ const getProjectModel = () => {
54
+ projectModel ??= mongoose_1.default.model("Project", projectSchema);
55
+ return projectModel;
56
+ };
57
+ exports.getProjectModel = getProjectModel;
58
+ /**
59
+ * Lazy stand-in for the `Project` model: every access registers it via `getProjectModel`.
60
+ * Statics, `new Project(...)` and `instanceof Project` work, but the proxy is not the model
61
+ * itself (`Project !== mongoose.models.Project`, `Object.keys(Project)` is empty, and reading
62
+ * `Project.prototype` throws).
63
+ * @deprecated Use `getProjectModel()`.
64
+ */
65
+ // A class target keeps the proxy constructible, like a mongoose Model.
66
+ exports.Project = new Proxy(class LazyProject {
67
+ }, {
68
+ construct: (_target, args) => Reflect.construct((0, exports.getProjectModel)(), args),
69
+ get: (_target, property) => {
70
+ const model = (0, exports.getProjectModel)();
71
+ const value = Reflect.get(model, property, model);
72
+ return typeof value === "function" ? value.bind(model) : value;
73
+ },
74
+ getPrototypeOf: () => Reflect.getPrototypeOf((0, exports.getProjectModel)()),
75
+ has: (_target, property) => Reflect.has((0, exports.getProjectModel)(), property),
76
+ set: (_target, property, value) => Reflect.set((0, exports.getProjectModel)(), property, value),
77
+ });