@terreno/ai 57.11.0 → 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 (45) 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/routes/approvals.js +2 -2
  6. package/dist/harness/routes/conversations.js +1 -1
  7. package/dist/harness/routes/tasks.js +85 -3
  8. package/dist/harness/runtime.js +7 -1
  9. package/dist/harness/subagent.d.ts +17 -2
  10. package/dist/harness/subagent.js +26 -2
  11. package/dist/index.d.ts +1 -1
  12. package/dist/index.js +3 -2
  13. package/dist/models/project.d.ts +13 -0
  14. package/dist/models/project.js +32 -2
  15. package/dist/observability/local/models/obsTrace.js +16 -2
  16. package/dist/observability/local/traceStore.d.ts +5 -0
  17. package/dist/observability/local/traceStore.js +5 -0
  18. package/dist/observability/routes/traces.js +2 -0
  19. package/dist/routes/projects.js +3 -3
  20. package/dist/service/chatTurn.js +1 -1
  21. package/dist/types/harness.d.ts +28 -2
  22. package/dist/types/observability.d.ts +3 -0
  23. package/package.json +56 -8
  24. package/src/aiApp.test.ts +15 -0
  25. package/src/aiApp.ts +9 -1
  26. package/src/harness/commit.ts +103 -1
  27. package/src/harness/routes/approvals.ts +2 -2
  28. package/src/harness/routes/conversations.ts +1 -1
  29. package/src/harness/routes/tasks.test.ts +34 -0
  30. package/src/harness/routes/tasks.ts +98 -3
  31. package/src/harness/runtime.ts +8 -1
  32. package/src/harness/subagent.test.ts +124 -3
  33. package/src/harness/subagent.ts +43 -1
  34. package/src/index.ts +1 -1
  35. package/src/isolated/lazyProjectModel.isolated.ts +25 -0
  36. package/src/models/project.ts +31 -1
  37. package/src/observability/local/models/obsTrace.ts +22 -5
  38. package/src/observability/local/traceStore.test.ts +7 -0
  39. package/src/observability/local/traceStore.ts +12 -0
  40. package/src/observability/routes/traces.test.ts +15 -0
  41. package/src/observability/routes/traces.ts +2 -0
  42. package/src/routes/projects.ts +4 -4
  43. package/src/service/chatTurn.ts +2 -2
  44. package/src/types/harness.ts +31 -2
  45. package/src/types/observability.ts +3 -0
@@ -140,6 +140,9 @@ class LocalTraceStore {
140
140
  if (query.sessionId) {
141
141
  filter.sessionId = query.sessionId;
142
142
  }
143
+ if (query.scope) {
144
+ filter.scope = query.scope;
145
+ }
143
146
  if (query.promptVersion !== undefined && !query.prompt) {
144
147
  throw new api_1.APIError({ status: 400, title: "prompt is required when promptVersion is set" });
145
148
  }
@@ -243,12 +246,14 @@ class LocalTraceStore {
243
246
  id: String(row._id),
244
247
  name: row.name,
245
248
  prompts: row.prompts,
249
+ scope: row.scope,
246
250
  scoreCount: counts.scoreCount,
247
251
  sensitive: row.sensitive,
248
252
  sessionId: row.sessionId,
249
253
  spanCount: counts.spanCount,
250
254
  startedAt: toIso(row.startedAt) ?? "",
251
255
  status: row.status,
256
+ tags: row.tags ?? [],
252
257
  usage: usageWithoutUndefinedCost(row.usage),
253
258
  userId: row.userId ? String(row.userId) : undefined,
254
259
  };
@@ -50,6 +50,7 @@ const addObservabilityTraceRoutes = (router, options) => {
50
50
  .withSummary("List observability traces")
51
51
  .withQueryParameter("prompt", { type: "string" }, { required: false })
52
52
  .withQueryParameter("promptVersion", { type: "number" }, { required: false })
53
+ .withQueryParameter("scope", { type: "string" }, { required: false })
53
54
  .withResponse(200, { data: { type: "array" } })
54
55
  .build()), (0, api_1.asyncHandler)(async (req, res) => {
55
56
  const prompt = typeof req.query.prompt === "string" ? req.query.prompt : undefined;
@@ -61,6 +62,7 @@ const addObservabilityTraceRoutes = (router, options) => {
61
62
  page: parsePositiveInt(req.query.page, 1),
62
63
  prompt,
63
64
  promptVersion: parsePromptVersion(req.query.promptVersion, prompt),
65
+ scope: typeof req.query.scope === "string" ? req.query.scope : undefined,
64
66
  sensitive: parseBoolean(req.query.sensitive),
65
67
  sessionId: typeof req.query.sessionId === "string" ? req.query.sessionId : undefined,
66
68
  status: req.query.status === "ok" || req.query.status === "error" ? req.query.status : undefined,
@@ -24,7 +24,7 @@ const addProjectRoutes = (router, options) => {
24
24
  if (!text || typeof text !== "string") {
25
25
  throw new api_1.APIError({ status: 400, title: "text is required" });
26
26
  }
27
- const project = await project_1.Project.findById(id);
27
+ const project = await (0, project_1.getProjectModel)().findById(id);
28
28
  if (!project) {
29
29
  throw new api_1.APIError({ status: 404, title: "Project not found" });
30
30
  }
@@ -48,7 +48,7 @@ const addProjectRoutes = (router, options) => {
48
48
  ], (0, api_1.asyncHandler)(async (req, res) => {
49
49
  const { id, memoryId } = req.params;
50
50
  const userId = req.user?._id;
51
- const project = await project_1.Project.findById(id);
51
+ const project = await (0, project_1.getProjectModel)().findById(id);
52
52
  if (!project) {
53
53
  throw new api_1.APIError({ status: 404, title: "Project not found" });
54
54
  }
@@ -63,7 +63,7 @@ const addProjectRoutes = (router, options) => {
63
63
  await project.save();
64
64
  return res.json({ data: { deleted: true } });
65
65
  }));
66
- router.use("/gpt/projects", (0, api_1.modelRouter)(project_1.Project, {
66
+ router.use("/gpt/projects", (0, api_1.modelRouter)((0, project_1.getProjectModel)(), {
67
67
  ...options?.openApiOptions,
68
68
  permissions: {
69
69
  create: [api_1.Permissions.IsAuthenticated],
@@ -670,7 +670,7 @@ const buildSystemPrompt = async ({ history, options, projectId, systemPrompt, us
670
670
  let effectiveSystemPrompt = systemPrompt;
671
671
  if (effectiveProjectId) {
672
672
  try {
673
- const project = await project_1.Project.findById(effectiveProjectId);
673
+ const project = await (0, project_1.getProjectModel)().findById(effectiveProjectId);
674
674
  if (project && project.userId.toString() === userId?.toString()) {
675
675
  const parts = [];
676
676
  if (project.systemContext) {
@@ -3,6 +3,23 @@ import type { LanguageModel, ModelMessage } from "ai";
3
3
  import type { Duration, DurationLike } from "luxon";
4
4
  import type mongoose from "mongoose";
5
5
  import type { ExecutionEnv } from "../harness/executionEnv";
6
+ import type { ObsPromptRef } from "./observability";
7
+ /**
8
+ * A prompt version a task used, recorded on its `ObsTrace.prompts`. A `PromptVersionRef`
9
+ * from `promptRegistry.get` fits as-is; its `body` is ignored.
10
+ */
11
+ export type HarnessPromptRef = ObsPromptRef;
12
+ /** A registry prompt passed as instructions: its `body` is used and its version recorded. */
13
+ export interface HarnessPromptInstructions extends HarnessPromptRef {
14
+ body: string;
15
+ }
16
+ /** Fields written onto the task's `ObsTrace`, shared by every child task and subagent. */
17
+ export interface HarnessTraceOptions {
18
+ /** App-defined scope (tenant, workspace) for metering; indexed with `created`. */
19
+ scope?: string;
20
+ /** App-defined labels for grouping traces. */
21
+ tags?: string[];
22
+ }
6
23
  /** Every lifecycle status a harness task can hold. */
7
24
  export declare const HARNESS_TASK_STATUSES: {
8
25
  readonly aborted: "aborted";
@@ -319,8 +336,13 @@ export interface HarnessMemo {
319
336
  export interface HarnessRunAgentOptions<Result> {
320
337
  /** The subagent's user message. A non-string value is sent as JSON. */
321
338
  input: unknown;
322
- /** Replaces the agent's instructions for this subagent conversation only. */
323
- instructions?: string;
339
+ /**
340
+ * Replaces the agent's instructions for this subagent conversation only. A registry
341
+ * prompt (`promptRegistry.get`) is used by its `body` and recorded on the trace.
342
+ */
343
+ instructions?: HarnessPromptInstructions | string;
344
+ /** Prompt versions this subagent used, recorded on the task's `ObsTrace.prompts`. */
345
+ prompts?: HarnessPromptRef[];
324
346
  /**
325
347
  * Structured output schema; defaults to the agent's own `output`. Requested through the
326
348
  * AI SDK's `Output.object`, then validated with this schema before it is returned.
@@ -383,8 +405,12 @@ export interface HarnessAbortOptions {
383
405
  userId?: mongoose.Types.ObjectId | string;
384
406
  }
385
407
  export interface HarnessCreateTaskOptions {
408
+ /** Prompt versions the task uses, recorded on its `ObsTrace.prompts`. */
409
+ prompts?: HarnessPromptRef[];
386
410
  /** Idempotency key: a second create with the same id returns the existing task. */
387
411
  requestId?: string;
412
+ /** Scope and tags for the task's `ObsTrace`; child tasks and subagents share it. */
413
+ trace?: HarnessTraceOptions;
388
414
  userId?: mongoose.Types.ObjectId | string;
389
415
  }
390
416
  /** How an interrupted task is resolved by an operator. */
@@ -72,10 +72,13 @@ export interface ObsTraceDocument extends mongoose.Document<mongoose.Types.Objec
72
72
  name: string;
73
73
  output?: unknown;
74
74
  prompts: ObsPromptRef[];
75
+ /** App-defined scope (tenant, workspace) set by `harness.createTask({trace: {scope}})`. */
76
+ scope?: string;
75
77
  sensitive: boolean;
76
78
  sessionId?: string;
77
79
  startedAt: Date;
78
80
  status: "error" | "ok";
81
+ tags: string[];
79
82
  updated: Date;
80
83
  usage?: ObsPromptUsage;
81
84
  userId?: mongoose.Types.ObjectId;
package/package.json CHANGED
@@ -10,7 +10,7 @@
10
10
  "@langfuse/otel": "^5.0.1",
11
11
  "@opentelemetry/api": "^1.9.0",
12
12
  "@opentelemetry/sdk-node": "0.217.0",
13
- "@terreno/blocks": "57.11.0",
13
+ "@terreno/blocks": "57.12.0",
14
14
  "ai": "^6.0.97",
15
15
  "ajv": "8.20.0",
16
16
  "csv-parse": "^6.1.0",
@@ -22,10 +22,10 @@
22
22
  "description": "Provider-agnostic AI service with streaming chat, request logging, and admin tools — part of Terreno, the batteries-included TypeScript framework for universal apps.",
23
23
  "devDependencies": {
24
24
  "@biomejs/biome": "^2.3.6",
25
- "@terreno/admin-backend": "57.11.0",
26
- "@terreno/api": "57.11.0",
27
- "@terreno/jobs": "57.11.0",
28
- "@terreno/test": "57.11.0",
25
+ "@terreno/admin-backend": "57.12.0",
26
+ "@terreno/api": "57.12.0",
27
+ "@terreno/jobs": "57.12.0",
28
+ "@terreno/test": "57.12.0",
29
29
  "@types/bun": "^1.4.0",
30
30
  "@types/express": "^5.0.6",
31
31
  "@types/luxon": "^3.7.1",
@@ -45,12 +45,42 @@
45
45
  "require": "./dist/index.js",
46
46
  "types": "./dist/index.d.ts"
47
47
  },
48
+ "./admin": {
49
+ "default": "./dist/aiAdminApp.js",
50
+ "import": "./dist/aiAdminApp.js",
51
+ "require": "./dist/aiAdminApp.js",
52
+ "types": "./dist/aiAdminApp.d.ts"
53
+ },
48
54
  "./harness": {
49
55
  "default": "./dist/harness/harness.js",
50
56
  "import": "./dist/harness/harness.js",
51
57
  "require": "./dist/harness/harness.js",
52
58
  "types": "./dist/harness/harness.d.ts"
53
59
  },
60
+ "./harness/agentLoop": {
61
+ "default": "./dist/harness/agentLoop.js",
62
+ "import": "./dist/harness/agentLoop.js",
63
+ "require": "./dist/harness/agentLoop.js",
64
+ "types": "./dist/harness/agentLoop.d.ts"
65
+ },
66
+ "./harness/commit": {
67
+ "default": "./dist/harness/commit.js",
68
+ "import": "./dist/harness/commit.js",
69
+ "require": "./dist/harness/commit.js",
70
+ "types": "./dist/harness/commit.d.ts"
71
+ },
72
+ "./harness/events": {
73
+ "default": "./dist/harness/events.js",
74
+ "import": "./dist/harness/events.js",
75
+ "require": "./dist/harness/events.js",
76
+ "types": "./dist/harness/events.d.ts"
77
+ },
78
+ "./harness/internalRuntime": {
79
+ "default": "./dist/harness/internalRuntime.js",
80
+ "import": "./dist/harness/internalRuntime.js",
81
+ "require": "./dist/harness/internalRuntime.js",
82
+ "types": "./dist/harness/internalRuntime.d.ts"
83
+ },
54
84
  "./harness/jobsRunner": {
55
85
  "default": "./dist/harness/runners/jobsRunner.js",
56
86
  "import": "./dist/harness/runners/jobsRunner.js",
@@ -69,6 +99,24 @@
69
99
  "require": "./dist/langfuseClient.js",
70
100
  "types": "./dist/langfuseClient.d.ts"
71
101
  },
102
+ "./observability/localPlugin": {
103
+ "default": "./dist/observability/local/localPlugin.js",
104
+ "import": "./dist/observability/local/localPlugin.js",
105
+ "require": "./dist/observability/local/localPlugin.js",
106
+ "types": "./dist/observability/local/localPlugin.d.ts"
107
+ },
108
+ "./observability/observabilityApp": {
109
+ "default": "./dist/observability/observabilityApp.js",
110
+ "import": "./dist/observability/observabilityApp.js",
111
+ "require": "./dist/observability/observabilityApp.js",
112
+ "types": "./dist/observability/observabilityApp.d.ts"
113
+ },
114
+ "./observability/promptStore": {
115
+ "default": "./dist/observability/local/promptStore.js",
116
+ "import": "./dist/observability/local/promptStore.js",
117
+ "require": "./dist/observability/local/promptStore.js",
118
+ "types": "./dist/observability/local/promptStore.d.ts"
119
+ },
72
120
  "./parseAiJson": {
73
121
  "default": "./dist/service/parseAiJson.js",
74
122
  "import": "./dist/service/parseAiJson.js",
@@ -88,8 +136,8 @@
88
136
  "name": "@terreno/ai",
89
137
  "peerDependencies": {
90
138
  "@ai-sdk/google-vertex": "^4.0.142",
91
- "@terreno/api": "57.11.0",
92
- "@terreno/jobs": "57.11.0",
139
+ "@terreno/api": "57.12.0",
140
+ "@terreno/jobs": "57.12.0",
93
141
  "mongoose": "^8.0.0 || ^9.0.0"
94
142
  },
95
143
  "peerDependenciesMeta": {
@@ -120,5 +168,5 @@
120
168
  "test:coverage": "bun run ../scripts/check-coverage.ts"
121
169
  },
122
170
  "types": "dist/index.d.ts",
123
- "version": "57.11.0"
171
+ "version": "57.12.0"
124
172
  }
package/src/aiApp.test.ts CHANGED
@@ -79,6 +79,21 @@ describe("AiApp", () => {
79
79
  expect(projects.status).toBe(200);
80
80
  });
81
81
 
82
+ it("skips the project routes with projects: false", async () => {
83
+ const {AIService} = await import("./service/aiService");
84
+ const aiService = new AIService({model: createMockModel() as unknown as LanguageModel});
85
+ const plugin = new AiApp({aiService, projects: false});
86
+ const app = new TerrenoApp({
87
+ configureApp: (router) => plugin.register(router as unknown as express.Application),
88
+ skipListen: true,
89
+ userModel: UserModel,
90
+ }).build();
91
+
92
+ const agent = await authAsUser(app);
93
+ expect((await agent.get("/gpt/histories")).status).toBe(200);
94
+ expect((await agent.get("/gpt/projects")).status).toBe(404);
95
+ });
96
+
82
97
  it("passes asks to the gpt routes, so the model is offered the ask tools", async () => {
83
98
  const {AIService} = await import("./service/aiService");
84
99
  const model = createMockModel();
package/src/aiApp.ts CHANGED
@@ -42,6 +42,11 @@ export interface AiAppOptions {
42
42
  mcpService?: MCPService;
43
43
  /** OpenAPI options passed through to route builders for spec generation. */
44
44
  openApiOptions?: Record<string, unknown>;
45
+ /**
46
+ * Mount the `/gpt/projects` routes, which register the `Project` model. Defaults to `true`;
47
+ * pass `false` when the app owns a model named `Project`.
48
+ */
49
+ projects?: boolean;
45
50
  /** Tool choice strategy for chat requests. Defaults to "auto" when tools are present. */
46
51
  toolChoice?: "auto" | "none" | "required";
47
52
  /** Cheap model ID used for generating conversation titles (e.g. "gemini-3.5-flash-lite"). Falls back to the main model if not set. */
@@ -97,6 +102,7 @@ export class AiApp implements TerrenoPlugin {
97
102
  maxSteps,
98
103
  mcpService,
99
104
  openApiOptions,
105
+ projects,
100
106
  titleModelId,
101
107
  toolChoice,
102
108
  tools,
@@ -122,7 +128,9 @@ export class AiApp implements TerrenoPlugin {
122
128
  addGptHistoryRoutes(router, {chat, openApiOptions});
123
129
  addGptRoutes(router, chat);
124
130
  addAiRequestsExplorerRoutes(router, {openApiOptions});
125
- addProjectRoutes(router, {openApiOptions});
131
+ if (projects !== false) {
132
+ addProjectRoutes(router, {openApiOptions});
133
+ }
126
134
 
127
135
  if (fileStorageService && gcsBucket) {
128
136
  addFileRoutes(router, {
@@ -17,6 +17,7 @@ import type {
17
17
  HarnessMessageModel,
18
18
  HarnessOwnerModel,
19
19
  HarnessOwnership,
20
+ HarnessPromptRef,
20
21
  HarnessReplayPolicy,
21
22
  HarnessResolveInterruptedOptions,
22
23
  HarnessTaskDefinition,
@@ -150,6 +151,94 @@ const findByRequestId = async ({
150
151
  return existing;
151
152
  };
152
153
 
154
+ /**
155
+ * Prompt refs as stored on `ObsTrace.prompts` (`{label?, name, version}`; a registry
156
+ * `body` is dropped), once each. Throws `invalidRequest` for a ref without a name, with a
157
+ * non-string label, or without a positive integer version.
158
+ */
159
+ export const tracePromptRefs = (refs: HarnessPromptRef[] | undefined): HarnessPromptRef[] => {
160
+ if (refs === undefined) {
161
+ return [];
162
+ }
163
+ if (!Array.isArray(refs)) {
164
+ throw harnessError({detail: "prompts must be an array", kind: "invalidRequest"});
165
+ }
166
+ const unique = new Map<string, HarnessPromptRef>();
167
+ for (const ref of refs) {
168
+ if (typeof ref?.name !== "string" || !ref.name.trim()) {
169
+ throw harnessError({detail: "Each prompt ref needs a name", kind: "invalidRequest"});
170
+ }
171
+ if (!Number.isInteger(ref.version) || ref.version < 1) {
172
+ throw harnessError({
173
+ detail: `Prompt ref "${ref.name}" needs a positive integer version`,
174
+ kind: "invalidRequest",
175
+ });
176
+ }
177
+ if (ref.label !== undefined && typeof ref.label !== "string") {
178
+ throw harnessError({
179
+ detail: `Prompt ref "${ref.name}" label must be a string`,
180
+ kind: "invalidRequest",
181
+ });
182
+ }
183
+ const normalized = {
184
+ ...(ref.label !== undefined ? {label: ref.label} : {}),
185
+ name: ref.name,
186
+ version: ref.version,
187
+ };
188
+ unique.set(JSON.stringify(normalized), normalized);
189
+ }
190
+ return [...unique.values()];
191
+ };
192
+
193
+ /** The `scope` and `tags` written onto a root task's `ObsTrace`. */
194
+ const traceFields = (
195
+ trace: HarnessCreateTaskOptions["trace"]
196
+ ): {scope?: string; tags?: string[]} => {
197
+ if (trace === undefined) {
198
+ return {};
199
+ }
200
+ const {scope, tags} = trace;
201
+ if (scope !== undefined && (typeof scope !== "string" || !scope.trim())) {
202
+ throw harnessError({detail: "trace.scope must be a non-empty string", kind: "invalidRequest"});
203
+ }
204
+ const isBlankTag = (tag: unknown): boolean => typeof tag !== "string" || !tag.trim();
205
+ if (tags !== undefined && (!Array.isArray(tags) || tags.some(isBlankTag))) {
206
+ throw harnessError({
207
+ detail: "trace.tags must be an array of non-empty strings",
208
+ kind: "invalidRequest",
209
+ });
210
+ }
211
+ return {
212
+ ...(scope !== undefined ? {scope} : {}),
213
+ ...(tags !== undefined ? {tags: [...new Set(tags)]} : {}),
214
+ };
215
+ };
216
+
217
+ /**
218
+ * Record `refs` on `traceId`'s `ObsTrace.prompts`, once each. Pass `session` to write
219
+ * inside a commit's transaction.
220
+ */
221
+ export const addTracePrompts = async ({
222
+ models,
223
+ refs,
224
+ session,
225
+ traceId,
226
+ }: {
227
+ models: HarnessModels;
228
+ refs: HarnessPromptRef[];
229
+ session?: ClientSession;
230
+ traceId: mongoose.Types.ObjectId;
231
+ }): Promise<void> => {
232
+ if (refs.length === 0) {
233
+ return;
234
+ }
235
+ await models.trace.updateOne(
236
+ {_id: traceId},
237
+ {$addToSet: {prompts: {$each: refs}}},
238
+ session ? {session} : {}
239
+ );
240
+ };
241
+
153
242
  /**
154
243
  * Insert a root task with its `ObsTrace` and root `CHAIN` span in one transaction.
155
244
  * A repeated `requestId` hits the unique index, rolls the whole transaction back (so no
@@ -185,11 +274,24 @@ export const createTaskRecords = async ({
185
274
  const startedAt = traceStartedAt.toJSDate();
186
275
  const userId = toObjectId(options.userId);
187
276
  const spanIdentity = taskSpanIdentity(definition, input);
277
+ const prompts = tracePromptRefs(options.prompts);
278
+ const traceExtras = traceFields(options.trace);
188
279
 
189
280
  try {
190
281
  return await inTransaction(async (session) => {
191
282
  await models.trace.create(
192
- [{_id: traceId, input, name: definition.key, startedAt, status: "ok", userId}],
283
+ [
284
+ {
285
+ _id: traceId,
286
+ input,
287
+ name: definition.key,
288
+ prompts,
289
+ startedAt,
290
+ status: "ok",
291
+ userId,
292
+ ...traceExtras,
293
+ },
294
+ ],
193
295
  {session}
194
296
  );
195
297
  await models.span.create(
@@ -73,7 +73,7 @@ export const addHarnessApprovalRoutes = (
73
73
  method: "POST",
74
74
  permissions: [Permissions.IsAuthenticated, canApprove as PermissionMethod<unknown>],
75
75
  summary: "Approve a harness approval",
76
- tag: "harness",
76
+ tag: "harnessapprovals",
77
77
  },
78
78
  reject: {
79
79
  body: rejectBody,
@@ -82,7 +82,7 @@ export const addHarnessApprovalRoutes = (
82
82
  method: "POST",
83
83
  permissions: [Permissions.IsAuthenticated, canApprove as PermissionMethod<unknown>],
84
84
  summary: "Reject a harness approval",
85
- tag: "harness",
85
+ tag: "harnessapprovals",
86
86
  },
87
87
  },
88
88
  permissions: {
@@ -84,7 +84,7 @@ export const addHarnessConversationRoutes = (
84
84
  method: "POST",
85
85
  permissions: [Permissions.IsAuthenticated, ownerOnly as PermissionMethod<unknown>],
86
86
  summary: "Submit a message to a harness conversation",
87
- tag: "harness",
87
+ tag: "harnessconversations",
88
88
  },
89
89
  },
90
90
  permissions: {
@@ -102,6 +102,40 @@ describe("Harness task routes", () => {
102
102
  await owner.patch(`/harness/tasks/${task._id}`).send({name: "x"}).expect(405);
103
103
  });
104
104
 
105
+ it("omits the lease from the task read and tags mutations with the task collection", async () => {
106
+ const {app, harness, login, ownerId} = await setup();
107
+ const task = await harness.createTask(parked, {}, {userId: ownerId});
108
+ await TaskModel.updateOne(
109
+ {_id: task._id},
110
+ {
111
+ $set: {
112
+ lease: {
113
+ owner: "runner-1",
114
+ token: "fence-secret",
115
+ },
116
+ },
117
+ }
118
+ );
119
+ const owner = await login(OWNER);
120
+ const read = await owner.get(`/harness/tasks/${task._id}`).expect(200);
121
+ expect(read.body.data.lease).toBeUndefined();
122
+ expect(read.body.data.name).toBe("test.parked");
123
+ expect((await TaskModel.findExactlyOne({_id: task._id})).lease?.token).toBe("fence-secret");
124
+
125
+ const spec = await supertest(app).get("/openapi.json").expect(200);
126
+ const taskRead = spec.body.paths["/harness/tasks/{id}"].get;
127
+ const taskSchema = taskRead.responses["200"].content["application/json"].schema;
128
+ expect(taskSchema.properties.lease).toBeUndefined();
129
+ expect(taskRead.tags).toEqual(["harnesstasks"]);
130
+ expect(spec.body.paths["/harness/tasks/{id}/abort"].post.tags).toEqual(["harnesstasks"]);
131
+ expect(spec.body.paths["/harness/approvals/{id}/approve"].post.tags).toEqual([
132
+ "harnessapprovals",
133
+ ]);
134
+ expect(spec.body.paths["/harness/conversations/{id}/submit"].post.tags).toEqual([
135
+ "harnessconversations",
136
+ ]);
137
+ });
138
+
105
139
  it("abort: the owner or an admin aborts with a reason; others get 403; ended tasks 409", async () => {
106
140
  const {harness, login, ownerId} = await setup({start: true});
107
141
  const first = await harness.createTask(parked, {}, {userId: ownerId});
@@ -8,6 +8,9 @@ import {
8
8
  } from "@terreno/api";
9
9
  import type express from "express";
10
10
 
11
+ /** OpenAPI tag shared with the task read query, so mutations refresh that cache. */
12
+ const TASK_OPENAPI_TAG = "harnesstasks";
13
+
11
14
  import type {HarnessTaskDocument} from "../../types/harness";
12
15
  import {
13
16
  HARNESS_RESOLVE_ACTIONS,
@@ -48,6 +51,91 @@ const adminOnly: PermissionMethod<HarnessTaskDocument> = (_method, user, task) =
48
51
 
49
52
  const isCommitConflict = (error: unknown): boolean => error instanceof HarnessCommitConflictError;
50
53
 
54
+ const withoutLease = (value: unknown): Record<string, unknown> => {
55
+ const doc = value as {toObject?: () => Record<string, unknown>};
56
+ const json =
57
+ typeof doc.toObject === "function" ? doc.toObject() : {...(value as Record<string, unknown>)};
58
+ const {lease: _lease, ...rest} = json;
59
+ return rest;
60
+ };
61
+
62
+ /** HTTP task reads omit the lease. The fencing token is a runner secret, not a client field. */
63
+ const taskResponseHandler: NonNullable<
64
+ ModelRouterOptions<HarnessTaskDocument>["responseHandler"]
65
+ > = async (value) => {
66
+ if (Array.isArray(value)) {
67
+ return value.map((doc) => withoutLease(doc)) as never;
68
+ }
69
+ return withoutLease(value) as never;
70
+ };
71
+
72
+ const stripLeaseFromOpenApiSpec = (spec: unknown): unknown => {
73
+ if (!spec || typeof spec !== "object" || !("responses" in spec)) {
74
+ return spec;
75
+ }
76
+ const responses = (spec as {responses?: unknown}).responses;
77
+ if (!responses || typeof responses !== "object") {
78
+ return spec;
79
+ }
80
+ const nextResponses: Record<string, unknown> = {};
81
+ for (const [status, response] of Object.entries(responses as Record<string, unknown>)) {
82
+ const content =
83
+ response && typeof response === "object"
84
+ ? (response as {content?: Record<string, unknown>}).content
85
+ : undefined;
86
+ const json = content?.["application/json"] as {schema?: Record<string, unknown>} | undefined;
87
+ const properties = json?.schema?.properties as Record<string, unknown> | undefined;
88
+ if (!properties || !("lease" in properties)) {
89
+ nextResponses[status] = response;
90
+ continue;
91
+ }
92
+ const {lease: _lease, ...rest} = properties;
93
+ const required = json?.schema?.required;
94
+ nextResponses[status] = {
95
+ ...(response as Record<string, unknown>),
96
+ content: {
97
+ ...content,
98
+ "application/json": {
99
+ ...json,
100
+ schema: {
101
+ ...json?.schema,
102
+ properties: rest,
103
+ ...(Array.isArray(required)
104
+ ? {required: required.filter((field) => field !== "lease")}
105
+ : {}),
106
+ },
107
+ },
108
+ },
109
+ };
110
+ }
111
+ return {...(spec as Record<string, unknown>), responses: nextResponses};
112
+ };
113
+
114
+ /** Task OpenAPI schemas must not publish `lease`, including its fencing token. */
115
+ const openApiWithoutTaskLease = (openApi: unknown): unknown => {
116
+ // The registrar is a middleware function with a `path` property, not a plain object.
117
+ if (
118
+ !openApi ||
119
+ (typeof openApi !== "object" && typeof openApi !== "function") ||
120
+ !("path" in openApi)
121
+ ) {
122
+ return openApi;
123
+ }
124
+ const registrar = openApi as {path: (spec: unknown) => unknown};
125
+ return new Proxy(registrar, {
126
+ get(target, prop, receiver) {
127
+ if (prop === "path") {
128
+ return (spec: unknown): unknown => target.path(stripLeaseFromOpenApiSpec(spec));
129
+ }
130
+ const value = Reflect.get(target, prop, receiver);
131
+ if (typeof value === "function") {
132
+ return value.bind(target);
133
+ }
134
+ return value;
135
+ },
136
+ });
137
+ };
138
+
51
139
  /**
52
140
  * Mount `{basePath}/tasks`: read (owner or admin), plus the `abort` (owner or admin) and
53
141
  * `resolveInterrupted` (admin) instance actions. Tasks are not listed or edited over HTTP.
@@ -111,7 +199,13 @@ export const addHarnessTaskRoutes = (
111
199
  router.use(
112
200
  `${basePath}/tasks`,
113
201
  modelRouter(model, {
114
- ...(openApi ? {openApi: openApi as ModelRouterOptions<HarnessTaskDocument>["openApi"]} : {}),
202
+ ...(openApi
203
+ ? {
204
+ openApi: openApiWithoutTaskLease(
205
+ openApi
206
+ ) as ModelRouterOptions<HarnessTaskDocument>["openApi"],
207
+ }
208
+ : {}),
115
209
  instanceActions: {
116
210
  abort: {
117
211
  body: abortBody,
@@ -121,7 +215,7 @@ export const addHarnessTaskRoutes = (
121
215
  method: "POST",
122
216
  permissions: [Permissions.IsAuthenticated, ownerOrAdmin as PermissionMethod<unknown>],
123
217
  summary: "Abort a harness task",
124
- tag: "harness",
218
+ tag: TASK_OPENAPI_TAG,
125
219
  },
126
220
  resolveInterrupted: {
127
221
  body: resolveBody,
@@ -131,7 +225,7 @@ export const addHarnessTaskRoutes = (
131
225
  method: "POST",
132
226
  permissions: [Permissions.IsAuthenticated, adminOnly as PermissionMethod<unknown>],
133
227
  summary: "Resolve an interrupted harness task",
134
- tag: "harness",
228
+ tag: TASK_OPENAPI_TAG,
135
229
  },
136
230
  },
137
231
  permissions: {
@@ -141,6 +235,7 @@ export const addHarnessTaskRoutes = (
141
235
  read: [Permissions.IsAuthenticated, ownerOrAdmin],
142
236
  update: [],
143
237
  },
238
+ responseHandler: taskResponseHandler,
144
239
  })
145
240
  );
146
241
  };