@theoremjs/agents 0.3.5-next.931.ge6a1c43 → 0.3.5-next.933.gfc0e83b

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.
@@ -82,10 +82,16 @@ export interface StageResult {
82
82
  abort?: boolean | {
83
83
  reason?: string;
84
84
  };
85
- /** `pre_tool`: refuse the call. `post_tool`: replace the result with this failure. */
85
+ /**
86
+ * `pre_tool`: refuse the call. `post_tool`: replace the result with this failure.
87
+ * `details`, a JSON object, become `failure.details`: the model reads them, and the guardrails
88
+ * read them first. Details that are not a JSON object are a `deny_invalid` warning, and the call
89
+ * is still refused, without details.
90
+ */
86
91
  deny?: {
87
92
  code?: string;
88
93
  message?: string;
94
+ details?: Record<string, unknown>;
89
95
  };
90
96
  /** `pre_tool` only — request a confirm/permission gate. */
91
97
  confirm?: true | {
@@ -166,6 +172,7 @@ export interface StageApplyOutput {
166
172
  deny?: {
167
173
  code: string;
168
174
  message: string;
175
+ details?: Record<string, unknown>;
169
176
  };
170
177
  confirm?: {
171
178
  summary?: string;
@@ -191,7 +191,19 @@ function applyDenyField(result, stage, out) {
191
191
  const message = typeof result.deny.message === 'string' && result.deny.message.trim()
192
192
  ? result.deny.message.trim()
193
193
  : 'Tool execution not authorized'; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
194
- out.deny = { code, message };
194
+ const details = result.deny.details;
195
+ if (details === undefined) {
196
+ out.deny = { code, message };
197
+ }
198
+ else if (isRecord(details) && jsonValueSchema.safeParse(details).success) {
199
+ out.deny = { code, message, details };
200
+ }
201
+ else {
202
+ // why: A refusal stands even when its details are bad; only the details are dropped.
203
+ out.deny = { code, message };
204
+ // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
205
+ warn(out.warnings, 'deny_invalid', 'deny', 'deny.details must be a JSON object');
206
+ }
195
207
  }
196
208
  }
197
209
  function applyLabelFailedField(result, stage, out) {
@@ -215,6 +215,7 @@ function* reviseAfterStages(post, guard, reproject, failure) {
215
215
  code: post.deny.code,
216
216
  kind: 'blocked',
217
217
  message: post.deny.message,
218
+ ...(post.deny.details ? { details: post.deny.details } : {}),
218
219
  });
219
220
  }
220
221
  if (post.mutate && 'details' in post.mutate) {
@@ -74,6 +74,7 @@ export type PostToolStageOutcome = {
74
74
  deny?: {
75
75
  code: string;
76
76
  message: string;
77
+ details?: Record<string, unknown>;
77
78
  };
78
79
  /** `output`: the caller validates and projects it again. `details`: the caller fails the call with them. */
79
80
  mutate?: {
@@ -139,7 +139,12 @@ async function* runPreToolStages(args) {
139
139
  return {
140
140
  ok: false,
141
141
  kind: 'failed',
142
- failure: { ...applied.deny, kind: 'blocked' },
142
+ failure: {
143
+ code: applied.deny.code,
144
+ kind: 'blocked',
145
+ message: applied.deny.message,
146
+ ...(applied.deny.details ? { details: applied.deny.details } : {}),
147
+ },
143
148
  denied: true,
144
149
  };
145
150
  }
@@ -1244,6 +1244,57 @@ export interface TurnRequest extends AgentRunRequest {
1244
1244
  /** What the user sent for the turn. */
1245
1245
  input?: TurnInput;
1246
1246
  }
1247
+ /** A background call's end that the model has not read. */
1248
+ export interface LateResult {
1249
+ /** The id the session keeps the call under. */
1250
+ operationId: string;
1251
+ outcome: ToolOperationOutcome;
1252
+ }
1253
+ /** A chat's ended results that no reply has read, as a {@linkcode LateResultsDecider} is asked. */
1254
+ export interface LateResultsAsk {
1255
+ /** The turn's `host`: what the app makes of the request. */
1256
+ host: unknown;
1257
+ /** The conversation reference the page holds. */
1258
+ conversation: string;
1259
+ results: readonly LateResult[];
1260
+ }
1261
+ /** A background call ended, and what Theorem lets the decider do about it. */
1262
+ export interface LateResultEnded {
1263
+ /** The `host` of the request that started the call. */
1264
+ host: unknown;
1265
+ result: LateResult;
1266
+ /**
1267
+ * Runs a reply to no message in `conversation`, as a page's wake does: the decider's `give` is
1268
+ * asked with `reason: 'wake'`. It runs nothing while a reply waits on gates or answers a
1269
+ * message, and a message posted meanwhile wins. The reference must stay the same across
1270
+ * writes, so a store whose reference changes with each write cannot wake from the server.
1271
+ */
1272
+ wake(conversation: string): Promise<void>;
1273
+ /** Tells the pages open on the session to read the chat again. */
1274
+ notify(): Promise<void>;
1275
+ }
1276
+ /**
1277
+ * Who tells the model that a background call ended. Theorem runs; the decider decides, and it
1278
+ * keeps its own count of what it told, such as a cap or quiet hours.
1279
+ */
1280
+ export interface LateResultsDecider {
1281
+ /**
1282
+ * The results a reply gives the model, by `operationId`. `reason` is `'message'` for a reply to
1283
+ * the person's message and `'wake'` for a reply to no message. Asked once for each reply, before
1284
+ * its model runs. The model reads each result you return once. One you leave out stays for a
1285
+ * later reply. A wake you give nothing runs no reply and leaves no mark.
1286
+ */
1287
+ give(ask: LateResultsAsk & {
1288
+ reason: 'message' | 'wake';
1289
+ }): readonly string[] | Promise<readonly string[]>;
1290
+ /**
1291
+ * Whether a page open on the chat wakes it now. Asked each time a page reads the chat, so it
1292
+ * must change nothing. Say yes only when `give` would give something. Unset, no page wakes it.
1293
+ */
1294
+ due?(ask: LateResultsAsk): boolean | Promise<boolean>;
1295
+ /** A background call ended. Use `wake` to reply from the server, with no page open. */
1296
+ ended?(ended: LateResultEnded): void | Promise<void>;
1297
+ }
1247
1298
  /**
1248
1299
  * How an application runs its turns: the one value its own call sites, its web handler and the
1249
1300
  * studio all use, so they cannot run a turn differently. An app that calls `runTurn` itself
@@ -1263,15 +1314,12 @@ export interface TurnWiring {
1263
1314
  */
1264
1315
  prepare?: (turn: NormalizedTurnRequest) => TurnRequest | Promise<TurnRequest>;
1265
1316
  /**
1266
- * Whether a wake may run: a reply to background results that no person asked for. Your limit on
1267
- * those replies, such as a cap or quiet hours. `host` is the turn's `host`, and `conversation` is
1268
- * the conversation reference the wake was posted with. A wake you refuse is not tried again for
1269
- * the same results; the next message reads them. Unset, every wake runs.
1317
+ * Who tells the model that a background call ended, and when. Theorem runs the replies; this
1318
+ * decides. Unset, the model is never told: no page wakes the chat, and no reply reads a late
1319
+ * result. `pageWakes` from `@theoremjs/web/server` lets the open page wake the chat, for an app
1320
+ * with no server of its own.
1270
1321
  */
1271
- authorizeWake?: (wake: {
1272
- host: unknown;
1273
- conversation: string;
1274
- }) => boolean | Promise<boolean>;
1322
+ lateResultsDecider?: LateResultsDecider;
1275
1323
  }
1276
1324
  /** A profile projected for a client, with its secrets and server-only fields removed. */
1277
1325
  export interface ProjectedProfile extends ProfileModelFields {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.931.ge6a1c43",
3
+ "version": "0.3.5-next.933.gfc0e83b",
4
4
  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
5
5
  "keywords": [
6
6
  "agent",