@truefoundry/trueforge-core 0.2.0-rc.4 → 0.2.0-rc.6

package/dist/agent-session/schemas/events.d.ts

@@ -1,7 +1,8 @@
 /**
  * Turn/session event product schemas. Event payloads come from the harness; this
- * module owns turn lifecycle events (turn.created / turn.done) and the persisted
- * event unions the store writes. SSE streaming envelopes stay in server/schemas.
+ * module owns turn lifecycle events (turn.created / turn.update / turn.done) and
+ * the persisted event unions the store writes. SSE streaming envelopes stay in
+ * server/schemas.
  */
 import { z } from '@hono/zod-openapi';
 import type { WithRegisteredPassthrough } from '../../core/events/PassthroughEvents';
@@ -22,6 +23,7 @@ export declare const EventType: {
     readonly USER_TOOL_RESPONSE: 'user.tool_response';
     readonly USER_MESSAGE: 'user.message';
     readonly TURN_CREATED: 'turn.created';
+    readonly TURN_UPDATE: 'turn.update';
     readonly TURN_DONE: 'turn.done';
 };
 export declare const TurnCreatedEventSchema: z.ZodObject<{
@@ -189,6 +191,40 @@ export declare const TurnDoneEventSchema: z.ZodObject<{
     created_at: z.ZodString;
     thread_id: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+export declare const ActionRequiredSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const TurnUpdateStatePausedSchema: z.ZodObject<{
+    status: z.ZodLiteral<"paused">;
+    action_required_on_events: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const TurnUpdateStateRunningSchema: z.ZodObject<{
+    status: z.ZodLiteral<"running">;
+}, z.core.$strip>;
+export declare const TurnUpdateStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"paused">;
+    action_required_on_events: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"running">;
+}, z.core.$strip>], "status">;
+export declare const TurnUpdateEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"turn.update">;
+    id: z.ZodString;
+    state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"paused">;
+        action_required_on_events: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        status: z.ZodLiteral<"running">;
+    }, z.core.$strip>], "status">;
+    created_at: z.ZodString;
+    thread_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
 /** Built-in durable turn events — lifecycle + content; no deltas, no passthrough. */
 export declare const SessionEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"turn.created">;
@@ -226,6 +262,19 @@ export declare const SessionEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>;
     created_at: z.ZodString;
     thread_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"turn.update">;
+    id: z.ZodString;
+    state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"paused">;
+        action_required_on_events: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        status: z.ZodLiteral<"running">;
+    }, z.core.$strip>], "status">;
+    created_at: z.ZodString;
+    thread_id: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"turn.done">;
     id: z.ZodString;
@@ -641,6 +690,19 @@ export declare const SessionEventItemSchema: z.ZodObject<{
         }, z.core.$strip>;
         created_at: z.ZodString;
         thread_id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"turn.update">;
+        id: z.ZodString;
+        state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"paused">;
+            action_required_on_events: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            status: z.ZodLiteral<"running">;
+        }, z.core.$strip>], "status">;
+        created_at: z.ZodString;
+        thread_id: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"turn.done">;
         id: z.ZodString;
@@ -1019,6 +1081,7 @@ export declare const SessionEventItemSchema: z.ZodObject<{
     }, z.core.$strip>], "type">;
 }, z.core.$strip>;
 export type TurnCreatedEvent = z.infer<typeof TurnCreatedEventSchema>;
+export type TurnUpdateEvent = z.infer<typeof TurnUpdateEventSchema>;
 export type TurnDoneEvent = z.infer<typeof TurnDoneEventSchema>;
 export type SessionEvent = z.infer<typeof SessionEventSchema>;
 /**

package/dist/agent-session/schemas/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/agent-session/schemas/events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AACtC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAsBrF,+EAA+E;AAC/E,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;2BAEN,cAAc;wBACjB,WAAW;CACd,CAAC;AAEX,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAWL,CAAC;AAE/B,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUL,CAAC;AAE5B,qFAAqF;AACrF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAcL,CAAC;AAE3B,4FAA4F;AAC5F,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKL,CAAC;AAE/B,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,CAAC,YAAY,CAAC,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AACF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,kBAAkB,CAAC;CAC3B"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/agent-session/schemas/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AACtC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAsBrF,+EAA+E;AAC/E,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;2BAEN,cAAc;0BACf,aAAa;wBACf,WAAW;CACd,CAAC;AAEX,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAWL,CAAC;AAE/B,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUL,CAAC;AAE5B,eAAO,MAAM,oBAAoB;;iBAIL,CAAC;AAE7B,eAAO,MAAM,2BAA2B;;;;;iBAOL,CAAC;AAEpC,eAAO,MAAM,4BAA4B;;iBAIL,CAAC;AAErC,eAAO,MAAM,qBAAqB;;;;;;;6BAGL,CAAC;AAE9B,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;iBAQL,CAAC;AAE9B,qFAAqF;AACrF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAeL,CAAC;AAE3B,4FAA4F;AAC5F,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKL,CAAC;AAE/B,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,CAAC,YAAY,CAAC,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AACF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,kBAAkB,CAAC;CAC3B"}

package/dist/agent-session/schemas/events.js

@@ -20,11 +20,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/agent-session/schemas/events.ts
 var events_exports = {};
 __export(events_exports, {
+  ActionRequiredSchema: () => ActionRequiredSchema,
   EventType: () => EventType,
   SessionEventItemSchema: () => SessionEventItemSchema,
   SessionEventSchema: () => SessionEventSchema,
   TurnCreatedEventSchema: () => TurnCreatedEventSchema,
-  TurnDoneEventSchema: () => TurnDoneEventSchema
+  TurnDoneEventSchema: () => TurnDoneEventSchema,
+  TurnUpdateEventSchema: () => TurnUpdateEventSchema,
+  TurnUpdateStatePausedSchema: () => TurnUpdateStatePausedSchema,
+  TurnUpdateStateRunningSchema: () => TurnUpdateStateRunningSchema,
+  TurnUpdateStateSchema: () => TurnUpdateStateSchema
 });
 module.exports = __toCommonJS(events_exports);
 var import_zod_openapi = require("@hono/zod-openapi");
@@ -33,6 +38,7 @@ var import_turn = require("./turn.js");
 var EventType = {
   ...import_schema.EventType,
   TURN_CREATED: "turn.created",
+  TURN_UPDATE: "turn.update",
   TURN_DONE: "turn.done"
 };
 var TurnCreatedEventSchema = import_zod_openapi.z.object({
@@ -52,8 +58,27 @@ var TurnDoneEventSchema = import_zod_openapi.z.object({
   created_at: import_zod_openapi.z.string().describe("ISO 8601 event timestamp."),
   thread_id: import_zod_openapi.z.string().nullable().describe("Thread that owns the event; null for turn-level lifecycle events.")
 }).openapi("TurnDoneEvent");
+var ActionRequiredSchema = import_zod_openapi.z.object({
+  id: import_schema.EventIdSchema
+}).openapi("ActionRequired");
+var TurnUpdateStatePausedSchema = import_zod_openapi.z.object({
+  status: import_zod_openapi.z.literal("paused").describe("Turn is paused waiting for required actions."),
+  action_required_on_events: import_zod_openapi.z.array(ActionRequiredSchema).describe("Events that still need a user or client action.")
+}).openapi("TurnUpdateStatePaused");
+var TurnUpdateStateRunningSchema = import_zod_openapi.z.object({
+  status: import_zod_openapi.z.literal("running").describe("Turn is executing.")
+}).openapi("TurnUpdateStateRunning");
+var TurnUpdateStateSchema = import_zod_openapi.z.discriminatedUnion("status", [TurnUpdateStatePausedSchema, TurnUpdateStateRunningSchema]).describe("Live non-terminal turn status.").openapi("TurnUpdateState");
+var TurnUpdateEventSchema = import_zod_openapi.z.object({
+  type: import_zod_openapi.z.literal(EventType.TURN_UPDATE).describe("Emitted when a turn pauses or resumes."),
+  id: import_schema.EventIdSchema,
+  state: TurnUpdateStateSchema,
+  created_at: import_zod_openapi.z.string().describe("ISO 8601 event timestamp."),
+  thread_id: import_zod_openapi.z.string().nullable().describe("Thread that owns the event; null for turn-level lifecycle events.")
+}).openapi("TurnUpdateEvent");
 var SessionEventSchema = import_zod_openapi.z.discriminatedUnion("type", [
   TurnCreatedEventSchema,
+  TurnUpdateEventSchema,
   TurnDoneEventSchema,
   import_schema.ModelMessageEventSchema,
   import_schema.ToolResponseEventSchema,
@@ -71,10 +96,15 @@ var SessionEventItemSchema = import_zod_openapi.z.object({
 }).openapi("SessionEventItem");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ActionRequiredSchema,
   EventType,
   SessionEventItemSchema,
   SessionEventSchema,
   TurnCreatedEventSchema,
-  TurnDoneEventSchema
+  TurnDoneEventSchema,
+  TurnUpdateEventSchema,
+  TurnUpdateStatePausedSchema,
+  TurnUpdateStateRunningSchema,
+  TurnUpdateStateSchema
 });
 //# sourceMappingURL=events.js.map

package/dist/agent-session/schemas/events.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/agent-session/schemas/events.ts"],"sourcesContent":["/**\n * Turn/session event product schemas. Event payloads come from the harness; this\n * module owns turn lifecycle events (turn.created / turn.done) and the persisted\n * event unions the store writes. SSE streaming envelopes stay in server/schemas.\n */\nimport { z } from '@hono/zod-openapi';\nimport type { WithRegisteredPassthrough } from '../../core/events/PassthroughEvents';\nimport {\n  EventIdSchema,\n  EventType as HarnessEventType,\n  MCPAuthRequiredEventSchema,\n  MCPInitializeEventSchema,\n  ModelMessageEventSchema,\n  SandboxCreatedEventSchema,\n  ThreadCreatedEventSchema,\n  ThreadDoneEventSchema,\n  ToolApprovalRequiredEventSchema,\n  ToolResponseEventSchema,\n  ToolResponseRequiredEventSchema,\n} from '../../core/events/schema';\nimport {\n  TurnInputItemSchema,\n  TurnStateCancelledSchema,\n  TurnStateDoneSchema,\n  TurnStateErrorSchema,\n  TurnStateRunningSchema,\n} from './turn';\n\n/** Harness event types plus the turn lifecycle types owned by agentSession. */\nexport const EventType = {\n  ...HarnessEventType,\n  TURN_CREATED: 'turn.created',\n  TURN_DONE: 'turn.done',\n} as const;\n\nexport const TurnCreatedEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_CREATED).describe('Emitted when a turn starts.'),\n    id: EventIdSchema,\n    turn_id: z.string().describe('Id of the newly created turn.'),\n    previous_turn_id: z.string().nullable().describe('Prior turn this turn chains from; null for a root turn.'),\n    input: z.array(TurnInputItemSchema).optional().describe('Input items supplied when the turn was created.'),\n    state: TurnStateRunningSchema,\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnCreatedEvent');\n\nexport const TurnDoneEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_DONE).describe('Emitted when a turn reaches a terminal state.'),\n    id: EventIdSchema,\n    state: z\n      .discriminatedUnion('status', [TurnStateDoneSchema, TurnStateCancelledSchema, TurnStateErrorSchema])\n      .describe('Terminal turn state (done, cancelled, or error).'),\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnDoneEvent');\n\n/** Built-in durable turn events — lifecycle + content; no deltas, no passthrough. */\nexport const SessionEventSchema = z\n  .discriminatedUnion('type', [\n    TurnCreatedEventSchema,\n    TurnDoneEventSchema,\n    ModelMessageEventSchema,\n    ToolResponseEventSchema,\n    ThreadCreatedEventSchema,\n    ThreadDoneEventSchema,\n    MCPAuthRequiredEventSchema,\n    MCPInitializeEventSchema,\n    SandboxCreatedEventSchema,\n    ToolApprovalRequiredEventSchema,\n    ToolResponseRequiredEventSchema,\n  ])\n  .openapi('SessionEvent');\n\n/** One row on the session timeline: which turn emitted the event plus the event payload. */\nexport const SessionEventItemSchema = z\n  .object({\n    turn_id: z.string().describe('Turn that emitted this event.'),\n    event: SessionEventSchema,\n  })\n  .openapi('SessionEventItem');\n\nexport type TurnCreatedEvent = z.infer<typeof TurnCreatedEventSchema>;\nexport type TurnDoneEvent = z.infer<typeof TurnDoneEventSchema>;\nexport type SessionEvent = z.infer<typeof SessionEventSchema>;\n/**\n * Durable turn event log entries: {@link SessionEvent} plus any registered\n * passthrough events. Every merged event must carry its monotonic ULID and\n * creation timestamp; shared by append and list operations.\n */\nexport type PersistedTurnEvent = WithRegisteredPassthrough<SessionEvent> & {\n  id: string;\n  created_at: string;\n};\nexport interface SessionEventItem {\n  turn_id: string;\n  event: PersistedTurnEvent;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,yBAAkB;AAElB,oBAYO;AACP,kBAMO;AAGA,IAAM,YAAY;AAAA,EACvB,GAAG,cAAAA;AAAA,EACH,cAAc;AAAA,EACd,WAAW;AACb;AAEO,IAAM,yBAAyB,qBACnC,OAAO;AAAA,EACN,MAAM,qBAAE,QAAQ,UAAU,YAAY,EAAE,SAAS,6BAA6B;AAAA,EAC9E,IAAI;AAAA,EACJ,SAAS,qBAAE,OAAO,EAAE,SAAS,+BAA+B;AAAA,EAC5D,kBAAkB,qBAAE,OAAO,EAAE,SAAS,EAAE,SAAS,yDAAyD;AAAA,EAC1G,OAAO,qBAAE,MAAM,+BAAmB,EAAE,SAAS,EAAE,SAAS,iDAAiD;AAAA,EACzG,OAAO;AAAA,EACP,YAAY,qBAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,qBAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,kBAAkB;AAEtB,IAAM,sBAAsB,qBAChC,OAAO;AAAA,EACN,MAAM,qBAAE,QAAQ,UAAU,SAAS,EAAE,SAAS,+CAA+C;AAAA,EAC7F,IAAI;AAAA,EACJ,OAAO,qBACJ,mBAAmB,UAAU,CAAC,iCAAqB,sCAA0B,gCAAoB,CAAC,EAClG,SAAS,kDAAkD;AAAA,EAC9D,YAAY,qBAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,qBAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,eAAe;AAGnB,IAAM,qBAAqB,qBAC/B,mBAAmB,QAAQ;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC,EACA,QAAQ,cAAc;AAGlB,IAAM,yBAAyB,qBACnC,OAAO;AAAA,EACN,SAAS,qBAAE,OAAO,EAAE,SAAS,+BAA+B;AAAA,EAC5D,OAAO;AACT,CAAC,EACA,QAAQ,kBAAkB;","names":["HarnessEventType"]}
+{"version":3,"sources":["../../../src/agent-session/schemas/events.ts"],"sourcesContent":["/**\n * Turn/session event product schemas. Event payloads come from the harness; this\n * module owns turn lifecycle events (turn.created / turn.update / turn.done) and\n * the persisted event unions the store writes. SSE streaming envelopes stay in\n * server/schemas.\n */\nimport { z } from '@hono/zod-openapi';\nimport type { WithRegisteredPassthrough } from '../../core/events/PassthroughEvents';\nimport {\n  EventIdSchema,\n  EventType as HarnessEventType,\n  MCPAuthRequiredEventSchema,\n  MCPInitializeEventSchema,\n  ModelMessageEventSchema,\n  SandboxCreatedEventSchema,\n  ThreadCreatedEventSchema,\n  ThreadDoneEventSchema,\n  ToolApprovalRequiredEventSchema,\n  ToolResponseEventSchema,\n  ToolResponseRequiredEventSchema,\n} from '../../core/events/schema';\nimport {\n  TurnInputItemSchema,\n  TurnStateCancelledSchema,\n  TurnStateDoneSchema,\n  TurnStateErrorSchema,\n  TurnStateRunningSchema,\n} from './turn';\n\n/** Harness event types plus the turn lifecycle types owned by agentSession. */\nexport const EventType = {\n  ...HarnessEventType,\n  TURN_CREATED: 'turn.created',\n  TURN_UPDATE: 'turn.update',\n  TURN_DONE: 'turn.done',\n} as const;\n\nexport const TurnCreatedEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_CREATED).describe('Emitted when a turn starts.'),\n    id: EventIdSchema,\n    turn_id: z.string().describe('Id of the newly created turn.'),\n    previous_turn_id: z.string().nullable().describe('Prior turn this turn chains from; null for a root turn.'),\n    input: z.array(TurnInputItemSchema).optional().describe('Input items supplied when the turn was created.'),\n    state: TurnStateRunningSchema,\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnCreatedEvent');\n\nexport const TurnDoneEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_DONE).describe('Emitted when a turn reaches a terminal state.'),\n    id: EventIdSchema,\n    state: z\n      .discriminatedUnion('status', [TurnStateDoneSchema, TurnStateCancelledSchema, TurnStateErrorSchema])\n      .describe('Terminal turn state (done, cancelled, or error).'),\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnDoneEvent');\n\nexport const ActionRequiredSchema = z\n  .object({\n    id: EventIdSchema,\n  })\n  .openapi('ActionRequired');\n\nexport const TurnUpdateStatePausedSchema = z\n  .object({\n    status: z.literal('paused').describe('Turn is paused waiting for required actions.'),\n    action_required_on_events: z\n      .array(ActionRequiredSchema)\n      .describe('Events that still need a user or client action.'),\n  })\n  .openapi('TurnUpdateStatePaused');\n\nexport const TurnUpdateStateRunningSchema = z\n  .object({\n    status: z.literal('running').describe('Turn is executing.'),\n  })\n  .openapi('TurnUpdateStateRunning');\n\nexport const TurnUpdateStateSchema = z\n  .discriminatedUnion('status', [TurnUpdateStatePausedSchema, TurnUpdateStateRunningSchema])\n  .describe('Live non-terminal turn status.')\n  .openapi('TurnUpdateState');\n\nexport const TurnUpdateEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_UPDATE).describe('Emitted when a turn pauses or resumes.'),\n    id: EventIdSchema,\n    state: TurnUpdateStateSchema,\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnUpdateEvent');\n\n/** Built-in durable turn events — lifecycle + content; no deltas, no passthrough. */\nexport const SessionEventSchema = z\n  .discriminatedUnion('type', [\n    TurnCreatedEventSchema,\n    TurnUpdateEventSchema,\n    TurnDoneEventSchema,\n    ModelMessageEventSchema,\n    ToolResponseEventSchema,\n    ThreadCreatedEventSchema,\n    ThreadDoneEventSchema,\n    MCPAuthRequiredEventSchema,\n    MCPInitializeEventSchema,\n    SandboxCreatedEventSchema,\n    ToolApprovalRequiredEventSchema,\n    ToolResponseRequiredEventSchema,\n  ])\n  .openapi('SessionEvent');\n\n/** One row on the session timeline: which turn emitted the event plus the event payload. */\nexport const SessionEventItemSchema = z\n  .object({\n    turn_id: z.string().describe('Turn that emitted this event.'),\n    event: SessionEventSchema,\n  })\n  .openapi('SessionEventItem');\n\nexport type TurnCreatedEvent = z.infer<typeof TurnCreatedEventSchema>;\nexport type TurnUpdateEvent = z.infer<typeof TurnUpdateEventSchema>;\nexport type TurnDoneEvent = z.infer<typeof TurnDoneEventSchema>;\nexport type SessionEvent = z.infer<typeof SessionEventSchema>;\n/**\n * Durable turn event log entries: {@link SessionEvent} plus any registered\n * passthrough events. Every merged event must carry its monotonic ULID and\n * creation timestamp; shared by append and list operations.\n */\nexport type PersistedTurnEvent = WithRegisteredPassthrough<SessionEvent> & {\n  id: string;\n  created_at: string;\n};\nexport interface SessionEventItem {\n  turn_id: string;\n  event: PersistedTurnEvent;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,yBAAkB;AAElB,oBAYO;AACP,kBAMO;AAGA,IAAM,YAAY;AAAA,EACvB,GAAG,cAAAA;AAAA,EACH,cAAc;AAAA,EACd,aAAa;AAAA,EACb,WAAW;AACb;AAEO,IAAM,yBAAyB,qBACnC,OAAO;AAAA,EACN,MAAM,qBAAE,QAAQ,UAAU,YAAY,EAAE,SAAS,6BAA6B;AAAA,EAC9E,IAAI;AAAA,EACJ,SAAS,qBAAE,OAAO,EAAE,SAAS,+BAA+B;AAAA,EAC5D,kBAAkB,qBAAE,OAAO,EAAE,SAAS,EAAE,SAAS,yDAAyD;AAAA,EAC1G,OAAO,qBAAE,MAAM,+BAAmB,EAAE,SAAS,EAAE,SAAS,iDAAiD;AAAA,EACzG,OAAO;AAAA,EACP,YAAY,qBAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,qBAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,kBAAkB;AAEtB,IAAM,sBAAsB,qBAChC,OAAO;AAAA,EACN,MAAM,qBAAE,QAAQ,UAAU,SAAS,EAAE,SAAS,+CAA+C;AAAA,EAC7F,IAAI;AAAA,EACJ,OAAO,qBACJ,mBAAmB,UAAU,CAAC,iCAAqB,sCAA0B,gCAAoB,CAAC,EAClG,SAAS,kDAAkD;AAAA,EAC9D,YAAY,qBAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,qBAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,eAAe;AAEnB,IAAM,uBAAuB,qBACjC,OAAO;AAAA,EACN,IAAI;AACN,CAAC,EACA,QAAQ,gBAAgB;AAEpB,IAAM,8BAA8B,qBACxC,OAAO;AAAA,EACN,QAAQ,qBAAE,QAAQ,QAAQ,EAAE,SAAS,8CAA8C;AAAA,EACnF,2BAA2B,qBACxB,MAAM,oBAAoB,EAC1B,SAAS,iDAAiD;AAC/D,CAAC,EACA,QAAQ,uBAAuB;AAE3B,IAAM,+BAA+B,qBACzC,OAAO;AAAA,EACN,QAAQ,qBAAE,QAAQ,SAAS,EAAE,SAAS,oBAAoB;AAC5D,CAAC,EACA,QAAQ,wBAAwB;AAE5B,IAAM,wBAAwB,qBAClC,mBAAmB,UAAU,CAAC,6BAA6B,4BAA4B,CAAC,EACxF,SAAS,gCAAgC,EACzC,QAAQ,iBAAiB;AAErB,IAAM,wBAAwB,qBAClC,OAAO;AAAA,EACN,MAAM,qBAAE,QAAQ,UAAU,WAAW,EAAE,SAAS,wCAAwC;AAAA,EACxF,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,YAAY,qBAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,qBAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,iBAAiB;AAGrB,IAAM,qBAAqB,qBAC/B,mBAAmB,QAAQ;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC,EACA,QAAQ,cAAc;AAGlB,IAAM,yBAAyB,qBACnC,OAAO;AAAA,EACN,SAAS,qBAAE,OAAO,EAAE,SAAS,+BAA+B;AAAA,EAC5D,OAAO;AACT,CAAC,EACA,QAAQ,kBAAkB;","names":["HarnessEventType"]}

package/dist/agent-session/schemas/events.mjs

@@ -23,6 +23,7 @@ import {
 var EventType = {
   ...HarnessEventType,
   TURN_CREATED: "turn.created",
+  TURN_UPDATE: "turn.update",
   TURN_DONE: "turn.done"
 };
 var TurnCreatedEventSchema = z.object({
@@ -42,8 +43,27 @@ var TurnDoneEventSchema = z.object({
   created_at: z.string().describe("ISO 8601 event timestamp."),
   thread_id: z.string().nullable().describe("Thread that owns the event; null for turn-level lifecycle events.")
 }).openapi("TurnDoneEvent");
+var ActionRequiredSchema = z.object({
+  id: EventIdSchema
+}).openapi("ActionRequired");
+var TurnUpdateStatePausedSchema = z.object({
+  status: z.literal("paused").describe("Turn is paused waiting for required actions."),
+  action_required_on_events: z.array(ActionRequiredSchema).describe("Events that still need a user or client action.")
+}).openapi("TurnUpdateStatePaused");
+var TurnUpdateStateRunningSchema = z.object({
+  status: z.literal("running").describe("Turn is executing.")
+}).openapi("TurnUpdateStateRunning");
+var TurnUpdateStateSchema = z.discriminatedUnion("status", [TurnUpdateStatePausedSchema, TurnUpdateStateRunningSchema]).describe("Live non-terminal turn status.").openapi("TurnUpdateState");
+var TurnUpdateEventSchema = z.object({
+  type: z.literal(EventType.TURN_UPDATE).describe("Emitted when a turn pauses or resumes."),
+  id: EventIdSchema,
+  state: TurnUpdateStateSchema,
+  created_at: z.string().describe("ISO 8601 event timestamp."),
+  thread_id: z.string().nullable().describe("Thread that owns the event; null for turn-level lifecycle events.")
+}).openapi("TurnUpdateEvent");
 var SessionEventSchema = z.discriminatedUnion("type", [
   TurnCreatedEventSchema,
+  TurnUpdateEventSchema,
   TurnDoneEventSchema,
   ModelMessageEventSchema,
   ToolResponseEventSchema,
@@ -60,10 +80,15 @@ var SessionEventItemSchema = z.object({
   event: SessionEventSchema
 }).openapi("SessionEventItem");
 export {
+  ActionRequiredSchema,
   EventType,
   SessionEventItemSchema,
   SessionEventSchema,
   TurnCreatedEventSchema,
-  TurnDoneEventSchema
+  TurnDoneEventSchema,
+  TurnUpdateEventSchema,
+  TurnUpdateStatePausedSchema,
+  TurnUpdateStateRunningSchema,
+  TurnUpdateStateSchema
 };
 //# sourceMappingURL=events.mjs.map

package/dist/agent-session/schemas/events.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/agent-session/schemas/events.ts"],"sourcesContent":["/**\n * Turn/session event product schemas. Event payloads come from the harness; this\n * module owns turn lifecycle events (turn.created / turn.done) and the persisted\n * event unions the store writes. SSE streaming envelopes stay in server/schemas.\n */\nimport { z } from '@hono/zod-openapi';\nimport type { WithRegisteredPassthrough } from '../../core/events/PassthroughEvents';\nimport {\n  EventIdSchema,\n  EventType as HarnessEventType,\n  MCPAuthRequiredEventSchema,\n  MCPInitializeEventSchema,\n  ModelMessageEventSchema,\n  SandboxCreatedEventSchema,\n  ThreadCreatedEventSchema,\n  ThreadDoneEventSchema,\n  ToolApprovalRequiredEventSchema,\n  ToolResponseEventSchema,\n  ToolResponseRequiredEventSchema,\n} from '../../core/events/schema';\nimport {\n  TurnInputItemSchema,\n  TurnStateCancelledSchema,\n  TurnStateDoneSchema,\n  TurnStateErrorSchema,\n  TurnStateRunningSchema,\n} from './turn';\n\n/** Harness event types plus the turn lifecycle types owned by agentSession. */\nexport const EventType = {\n  ...HarnessEventType,\n  TURN_CREATED: 'turn.created',\n  TURN_DONE: 'turn.done',\n} as const;\n\nexport const TurnCreatedEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_CREATED).describe('Emitted when a turn starts.'),\n    id: EventIdSchema,\n    turn_id: z.string().describe('Id of the newly created turn.'),\n    previous_turn_id: z.string().nullable().describe('Prior turn this turn chains from; null for a root turn.'),\n    input: z.array(TurnInputItemSchema).optional().describe('Input items supplied when the turn was created.'),\n    state: TurnStateRunningSchema,\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnCreatedEvent');\n\nexport const TurnDoneEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_DONE).describe('Emitted when a turn reaches a terminal state.'),\n    id: EventIdSchema,\n    state: z\n      .discriminatedUnion('status', [TurnStateDoneSchema, TurnStateCancelledSchema, TurnStateErrorSchema])\n      .describe('Terminal turn state (done, cancelled, or error).'),\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnDoneEvent');\n\n/** Built-in durable turn events — lifecycle + content; no deltas, no passthrough. */\nexport const SessionEventSchema = z\n  .discriminatedUnion('type', [\n    TurnCreatedEventSchema,\n    TurnDoneEventSchema,\n    ModelMessageEventSchema,\n    ToolResponseEventSchema,\n    ThreadCreatedEventSchema,\n    ThreadDoneEventSchema,\n    MCPAuthRequiredEventSchema,\n    MCPInitializeEventSchema,\n    SandboxCreatedEventSchema,\n    ToolApprovalRequiredEventSchema,\n    ToolResponseRequiredEventSchema,\n  ])\n  .openapi('SessionEvent');\n\n/** One row on the session timeline: which turn emitted the event plus the event payload. */\nexport const SessionEventItemSchema = z\n  .object({\n    turn_id: z.string().describe('Turn that emitted this event.'),\n    event: SessionEventSchema,\n  })\n  .openapi('SessionEventItem');\n\nexport type TurnCreatedEvent = z.infer<typeof TurnCreatedEventSchema>;\nexport type TurnDoneEvent = z.infer<typeof TurnDoneEventSchema>;\nexport type SessionEvent = z.infer<typeof SessionEventSchema>;\n/**\n * Durable turn event log entries: {@link SessionEvent} plus any registered\n * passthrough events. Every merged event must carry its monotonic ULID and\n * creation timestamp; shared by append and list operations.\n */\nexport type PersistedTurnEvent = WithRegisteredPassthrough<SessionEvent> & {\n  id: string;\n  created_at: string;\n};\nexport interface SessionEventItem {\n  turn_id: string;\n  event: PersistedTurnEvent;\n}\n"],"mappings":";AAKA,SAAS,SAAS;AAElB;AAAA,EACE;AAAA,EACA,aAAa;AAAA,EACb;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGA,IAAM,YAAY;AAAA,EACvB,GAAG;AAAA,EACH,cAAc;AAAA,EACd,WAAW;AACb;AAEO,IAAM,yBAAyB,EACnC,OAAO;AAAA,EACN,MAAM,EAAE,QAAQ,UAAU,YAAY,EAAE,SAAS,6BAA6B;AAAA,EAC9E,IAAI;AAAA,EACJ,SAAS,EAAE,OAAO,EAAE,SAAS,+BAA+B;AAAA,EAC5D,kBAAkB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,yDAAyD;AAAA,EAC1G,OAAO,EAAE,MAAM,mBAAmB,EAAE,SAAS,EAAE,SAAS,iDAAiD;AAAA,EACzG,OAAO;AAAA,EACP,YAAY,EAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,kBAAkB;AAEtB,IAAM,sBAAsB,EAChC,OAAO;AAAA,EACN,MAAM,EAAE,QAAQ,UAAU,SAAS,EAAE,SAAS,+CAA+C;AAAA,EAC7F,IAAI;AAAA,EACJ,OAAO,EACJ,mBAAmB,UAAU,CAAC,qBAAqB,0BAA0B,oBAAoB,CAAC,EAClG,SAAS,kDAAkD;AAAA,EAC9D,YAAY,EAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,eAAe;AAGnB,IAAM,qBAAqB,EAC/B,mBAAmB,QAAQ;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC,EACA,QAAQ,cAAc;AAGlB,IAAM,yBAAyB,EACnC,OAAO;AAAA,EACN,SAAS,EAAE,OAAO,EAAE,SAAS,+BAA+B;AAAA,EAC5D,OAAO;AACT,CAAC,EACA,QAAQ,kBAAkB;","names":[]}
+{"version":3,"sources":["../../../src/agent-session/schemas/events.ts"],"sourcesContent":["/**\n * Turn/session event product schemas. Event payloads come from the harness; this\n * module owns turn lifecycle events (turn.created / turn.update / turn.done) and\n * the persisted event unions the store writes. SSE streaming envelopes stay in\n * server/schemas.\n */\nimport { z } from '@hono/zod-openapi';\nimport type { WithRegisteredPassthrough } from '../../core/events/PassthroughEvents';\nimport {\n  EventIdSchema,\n  EventType as HarnessEventType,\n  MCPAuthRequiredEventSchema,\n  MCPInitializeEventSchema,\n  ModelMessageEventSchema,\n  SandboxCreatedEventSchema,\n  ThreadCreatedEventSchema,\n  ThreadDoneEventSchema,\n  ToolApprovalRequiredEventSchema,\n  ToolResponseEventSchema,\n  ToolResponseRequiredEventSchema,\n} from '../../core/events/schema';\nimport {\n  TurnInputItemSchema,\n  TurnStateCancelledSchema,\n  TurnStateDoneSchema,\n  TurnStateErrorSchema,\n  TurnStateRunningSchema,\n} from './turn';\n\n/** Harness event types plus the turn lifecycle types owned by agentSession. */\nexport const EventType = {\n  ...HarnessEventType,\n  TURN_CREATED: 'turn.created',\n  TURN_UPDATE: 'turn.update',\n  TURN_DONE: 'turn.done',\n} as const;\n\nexport const TurnCreatedEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_CREATED).describe('Emitted when a turn starts.'),\n    id: EventIdSchema,\n    turn_id: z.string().describe('Id of the newly created turn.'),\n    previous_turn_id: z.string().nullable().describe('Prior turn this turn chains from; null for a root turn.'),\n    input: z.array(TurnInputItemSchema).optional().describe('Input items supplied when the turn was created.'),\n    state: TurnStateRunningSchema,\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnCreatedEvent');\n\nexport const TurnDoneEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_DONE).describe('Emitted when a turn reaches a terminal state.'),\n    id: EventIdSchema,\n    state: z\n      .discriminatedUnion('status', [TurnStateDoneSchema, TurnStateCancelledSchema, TurnStateErrorSchema])\n      .describe('Terminal turn state (done, cancelled, or error).'),\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnDoneEvent');\n\nexport const ActionRequiredSchema = z\n  .object({\n    id: EventIdSchema,\n  })\n  .openapi('ActionRequired');\n\nexport const TurnUpdateStatePausedSchema = z\n  .object({\n    status: z.literal('paused').describe('Turn is paused waiting for required actions.'),\n    action_required_on_events: z\n      .array(ActionRequiredSchema)\n      .describe('Events that still need a user or client action.'),\n  })\n  .openapi('TurnUpdateStatePaused');\n\nexport const TurnUpdateStateRunningSchema = z\n  .object({\n    status: z.literal('running').describe('Turn is executing.'),\n  })\n  .openapi('TurnUpdateStateRunning');\n\nexport const TurnUpdateStateSchema = z\n  .discriminatedUnion('status', [TurnUpdateStatePausedSchema, TurnUpdateStateRunningSchema])\n  .describe('Live non-terminal turn status.')\n  .openapi('TurnUpdateState');\n\nexport const TurnUpdateEventSchema = z\n  .object({\n    type: z.literal(EventType.TURN_UPDATE).describe('Emitted when a turn pauses or resumes.'),\n    id: EventIdSchema,\n    state: TurnUpdateStateSchema,\n    created_at: z.string().describe('ISO 8601 event timestamp.'),\n    thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),\n  })\n  .openapi('TurnUpdateEvent');\n\n/** Built-in durable turn events — lifecycle + content; no deltas, no passthrough. */\nexport const SessionEventSchema = z\n  .discriminatedUnion('type', [\n    TurnCreatedEventSchema,\n    TurnUpdateEventSchema,\n    TurnDoneEventSchema,\n    ModelMessageEventSchema,\n    ToolResponseEventSchema,\n    ThreadCreatedEventSchema,\n    ThreadDoneEventSchema,\n    MCPAuthRequiredEventSchema,\n    MCPInitializeEventSchema,\n    SandboxCreatedEventSchema,\n    ToolApprovalRequiredEventSchema,\n    ToolResponseRequiredEventSchema,\n  ])\n  .openapi('SessionEvent');\n\n/** One row on the session timeline: which turn emitted the event plus the event payload. */\nexport const SessionEventItemSchema = z\n  .object({\n    turn_id: z.string().describe('Turn that emitted this event.'),\n    event: SessionEventSchema,\n  })\n  .openapi('SessionEventItem');\n\nexport type TurnCreatedEvent = z.infer<typeof TurnCreatedEventSchema>;\nexport type TurnUpdateEvent = z.infer<typeof TurnUpdateEventSchema>;\nexport type TurnDoneEvent = z.infer<typeof TurnDoneEventSchema>;\nexport type SessionEvent = z.infer<typeof SessionEventSchema>;\n/**\n * Durable turn event log entries: {@link SessionEvent} plus any registered\n * passthrough events. Every merged event must carry its monotonic ULID and\n * creation timestamp; shared by append and list operations.\n */\nexport type PersistedTurnEvent = WithRegisteredPassthrough<SessionEvent> & {\n  id: string;\n  created_at: string;\n};\nexport interface SessionEventItem {\n  turn_id: string;\n  event: PersistedTurnEvent;\n}\n"],"mappings":";AAMA,SAAS,SAAS;AAElB;AAAA,EACE;AAAA,EACA,aAAa;AAAA,EACb;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGA,IAAM,YAAY;AAAA,EACvB,GAAG;AAAA,EACH,cAAc;AAAA,EACd,aAAa;AAAA,EACb,WAAW;AACb;AAEO,IAAM,yBAAyB,EACnC,OAAO;AAAA,EACN,MAAM,EAAE,QAAQ,UAAU,YAAY,EAAE,SAAS,6BAA6B;AAAA,EAC9E,IAAI;AAAA,EACJ,SAAS,EAAE,OAAO,EAAE,SAAS,+BAA+B;AAAA,EAC5D,kBAAkB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,yDAAyD;AAAA,EAC1G,OAAO,EAAE,MAAM,mBAAmB,EAAE,SAAS,EAAE,SAAS,iDAAiD;AAAA,EACzG,OAAO;AAAA,EACP,YAAY,EAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,kBAAkB;AAEtB,IAAM,sBAAsB,EAChC,OAAO;AAAA,EACN,MAAM,EAAE,QAAQ,UAAU,SAAS,EAAE,SAAS,+CAA+C;AAAA,EAC7F,IAAI;AAAA,EACJ,OAAO,EACJ,mBAAmB,UAAU,CAAC,qBAAqB,0BAA0B,oBAAoB,CAAC,EAClG,SAAS,kDAAkD;AAAA,EAC9D,YAAY,EAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,eAAe;AAEnB,IAAM,uBAAuB,EACjC,OAAO;AAAA,EACN,IAAI;AACN,CAAC,EACA,QAAQ,gBAAgB;AAEpB,IAAM,8BAA8B,EACxC,OAAO;AAAA,EACN,QAAQ,EAAE,QAAQ,QAAQ,EAAE,SAAS,8CAA8C;AAAA,EACnF,2BAA2B,EACxB,MAAM,oBAAoB,EAC1B,SAAS,iDAAiD;AAC/D,CAAC,EACA,QAAQ,uBAAuB;AAE3B,IAAM,+BAA+B,EACzC,OAAO;AAAA,EACN,QAAQ,EAAE,QAAQ,SAAS,EAAE,SAAS,oBAAoB;AAC5D,CAAC,EACA,QAAQ,wBAAwB;AAE5B,IAAM,wBAAwB,EAClC,mBAAmB,UAAU,CAAC,6BAA6B,4BAA4B,CAAC,EACxF,SAAS,gCAAgC,EACzC,QAAQ,iBAAiB;AAErB,IAAM,wBAAwB,EAClC,OAAO;AAAA,EACN,MAAM,EAAE,QAAQ,UAAU,WAAW,EAAE,SAAS,wCAAwC;AAAA,EACxF,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,YAAY,EAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EAC3D,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,mEAAmE;AAC/G,CAAC,EACA,QAAQ,iBAAiB;AAGrB,IAAM,qBAAqB,EAC/B,mBAAmB,QAAQ;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC,EACA,QAAQ,cAAc;AAGlB,IAAM,yBAAyB,EACnC,OAAO;AAAA,EACN,SAAS,EAAE,OAAO,EAAE,SAAS,+BAA+B;AAAA,EAC5D,OAAO;AACT,CAAC,EACA,QAAQ,kBAAkB;","names":[]}

package/dist/agent-session/schemas/session.d.ts

@@ -99,6 +99,9 @@ export declare const SessionAgentInlineSchema: z.ZodObject<{
             ask_user_questions: z.ZodDefault<z.ZodObject<{
                 enabled: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>>;
+            web_search: z.ZodDefault<z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strict>;
@@ -191,6 +194,9 @@ export declare const SessionAgentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             ask_user_questions: z.ZodDefault<z.ZodObject<{
                 enabled: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>>;
+            web_search: z.ZodDefault<z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strict>], "type">;
@@ -303,6 +309,9 @@ export declare const SessionSchema: z.ZodObject<{
                 ask_user_questions: z.ZodDefault<z.ZodObject<{
                     enabled: z.ZodDefault<z.ZodBoolean>;
                 }, z.core.$strip>>;
+                web_search: z.ZodDefault<z.ZodObject<{
+                    enabled: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strip>>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
     }, z.core.$strict>], "type">;

package/dist/agent-session/schemas/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/agent-session/schemas/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAetC,eAAO,MAAM,qBAAqB,uCAiBL,CAAC;AAE9B,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,oBAAoB;;;;kBAQL,CAAC;AAE7B,eAAO,MAAM,2BAA2B;;;;kBAWL,CAAC;AAEpC,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAML,CAAC;AAEjC,oEAAoE;AACpE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAEL,CAAC;AAE3B,eAAO,MAAM,uBAAuB;;EAAoD,CAAC;AAEzF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAYxE,eAAO,MAAM,2BAA2B;;;;kBAAiE,CAAC;AAE1G;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;kBAEL,CAAC;AAE5B,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAYL,CAAC;AAEtB,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/agent-session/schemas/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAetC,eAAO,MAAM,qBAAqB,uCAiBL,CAAC;AAE9B,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,oBAAoB;;;;kBAQL,CAAC;AAE7B,eAAO,MAAM,2BAA2B;;;;kBAWL,CAAC;AAEpC,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAML,CAAC;AAEjC,oEAAoE;AACpE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAEL,CAAC;AAE3B,eAAO,MAAM,uBAAuB;;EAAoD,CAAC;AAEzF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAYxE,eAAO,MAAM,2BAA2B;;;;kBAAiE,CAAC;AAE1G;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;kBAEL,CAAC;AAE5B,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAYL,CAAC;AAEtB,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/core/capabilities/builtins/WebSearch.d.ts

@@ -0,0 +1,32 @@
+import { InstructionBuilder } from '../../InstructionBuilder';
+import { LocalToolMCP, type ToolDefinition } from '../../mcp/LocalToolMCP';
+import type { AgentTracing } from '../../tracing/AgentTracing';
+import type { IWebSearchProvider } from '../../web-search/WebSearchProvider';
+import type { AgentCapability } from '../AgentCapability';
+export declare const WEB_SEARCH_SERVER_ID = "web-search";
+export declare const WEB_SEARCH_TOOL_NAME = "web_search";
+export declare const WEB_FETCH_TOOL_NAME = "web_fetch";
+export declare const WEB_SEARCH_REMINDER_TAG = "web-search";
+/**
+ * Cross-tool policy (when / how to combine search + fetch).
+ * Per-tool behavior and params stay on tool descriptions / schema describes.
+ */
+export declare function buildWebSearchInstruction(builder: InstructionBuilder): void;
+export declare class WebSearchTools extends LocalToolMCP {
+    #private;
+    readonly name = "web-search";
+    readonly displayName = "WebSearch";
+    constructor(options: {
+        provider: IWebSearchProvider;
+        tracing: AgentTracing;
+    });
+    private tools;
+    protected getTools(): ToolDefinition[];
+    private runSearch;
+    private runFetch;
+}
+export declare function webSearch(options: {
+    provider: IWebSearchProvider;
+    tracing: AgentTracing;
+}): AgentCapability;
+//# sourceMappingURL=WebSearch.d.ts.map

package/dist/core/capabilities/builtins/WebSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearch.d.ts","sourceRoot":"","sources":["../../../../src/core/capabilities/builtins/WebSearch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAc,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,eAAO,MAAM,oBAAoB,eAAe,CAAC;AACjD,eAAO,MAAM,oBAAoB,eAAe,CAAC;AACjD,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAC/C,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAyCpD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAiB3E;AAED,qBAAa,cAAe,SAAQ,YAAY;;IAC9C,QAAQ,CAAC,IAAI,gBAAwB;IACrC,QAAQ,CAAC,WAAW,eAAe;IAGnC,YAAY,OAAO,EAAE;QAAE,QAAQ,EAAE,kBAAkB,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,EAG3E;IAED,OAAO,CAAC,KAAK,CAaX;IAEF,SAAS,CAAC,QAAQ,IAAI,cAAc,EAAE,CAErC;YAEa,SAAS;YAQT,QAAQ;CAOvB;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAAG,eAAe,CAK3G"}

package/dist/core/capabilities/builtins/WebSearch.js

@@ -0,0 +1,137 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/capabilities/builtins/WebSearch.ts
+var WebSearch_exports = {};
+__export(WebSearch_exports, {
+  WEB_FETCH_TOOL_NAME: () => WEB_FETCH_TOOL_NAME,
+  WEB_SEARCH_REMINDER_TAG: () => WEB_SEARCH_REMINDER_TAG,
+  WEB_SEARCH_SERVER_ID: () => WEB_SEARCH_SERVER_ID,
+  WEB_SEARCH_TOOL_NAME: () => WEB_SEARCH_TOOL_NAME,
+  WebSearchTools: () => WebSearchTools,
+  buildWebSearchInstruction: () => buildWebSearchInstruction,
+  webSearch: () => webSearch
+});
+module.exports = __toCommonJS(WebSearch_exports);
+var import_dedent = __toESM(require("dedent"), 1);
+var import_zod = require("zod");
+var import_InstructionBuilder = require("../../InstructionBuilder.js");
+var import_IMCPServer = require("../../mcp/IMCPServer.js");
+var import_LocalToolMCP = require("../../mcp/LocalToolMCP.js");
+var WEB_SEARCH_SERVER_ID = "web-search";
+var WEB_SEARCH_TOOL_NAME = "web_search";
+var WEB_FETCH_TOOL_NAME = "web_fetch";
+var WEB_SEARCH_REMINDER_TAG = "web-search";
+var webSearchInputSchema = import_zod.z.object({
+  search_queries: import_zod.z.array(import_zod.z.string().min(1)).min(1).max(5).describe(
+    'Keyword search queries (prefer 3\u20136 words each; 2\u20133 queries often beat one long query). Operators such as site:domain, filetype:pdf, intitle:word, -term, and "exact phrase" may work when the backend supports them.'
+  ),
+  objective: import_zod.z.string().min(1).optional().describe("Natural-language goal for the search. Helps the backend focus hits when provided.")
+}).strict();
+var webFetchInputSchema = import_zod.z.object({
+  urls: import_zod.z.array(import_zod.z.url()).min(1).max(5).describe("Page URLs to extract (up to 5). Prefer specific hit URLs from web_search."),
+  objective: import_zod.z.string().min(1).optional().describe("Optional goal used to focus extracted excerpts when the page is large.")
+}).strict();
+var WEB_SEARCH_TOOL_DESCRIPTION = "Search the web. Returns ranked hits with titles, URLs, and snippets. Prefer concise keyword queries; use multiple related queries in one call when useful.";
+var WEB_FETCH_TOOL_DESCRIPTION = `Extract page content from URLs as markdown/text (no LLM summarization). Prefer specific hit URLs from ${WEB_SEARCH_TOOL_NAME} when snippets are not enough.`;
+function buildWebSearchInstruction(builder) {
+  builder.addSection(
+    WEB_SEARCH_REMINDER_TAG,
+    import_dedent.default`
+      The Agent has two system tools for live web access: ${WEB_SEARCH_TOOL_NAME} (search) and ${WEB_FETCH_TOOL_NAME} (extract page content).
+
+      When to use them:
+      - The user asks to search, browse, verify, look up, or get latest information.
+      - Facts may have changed recently (news, prices, laws, schedules, product specs, software APIs/docs, people in roles, rates, scores).
+      - The answer needs direct quotes, links, or precise source attribution.
+      - A specific page, paper, dataset, or site is referenced and its contents were not provided.
+
+      How to use them:
+      - Start with ${WEB_SEARCH_TOOL_NAME} for discovery; follow with ${WEB_FETCH_TOOL_NAME} on the best URLs when snippets are not enough.
+      - Prefer primary and authoritative sources.
+    `.trim()
+  );
+}
+var WebSearchTools = class extends import_LocalToolMCP.LocalToolMCP {
+  name = WEB_SEARCH_SERVER_ID;
+  displayName = "WebSearch";
+  #provider;
+  constructor(options) {
+    super({ tracing: options.tracing });
+    this.#provider = options.provider;
+  }
+  tools = [
+    (0, import_LocalToolMCP.defineTool)({
+      name: WEB_SEARCH_TOOL_NAME,
+      description: WEB_SEARCH_TOOL_DESCRIPTION,
+      schema: webSearchInputSchema,
+      handler: (input) => this.runSearch(input)
+    }),
+    (0, import_LocalToolMCP.defineTool)({
+      name: WEB_FETCH_TOOL_NAME,
+      description: WEB_FETCH_TOOL_DESCRIPTION,
+      schema: webFetchInputSchema,
+      handler: (input) => this.runFetch(input)
+    })
+  ];
+  getTools() {
+    return this.tools;
+  }
+  async runSearch(input) {
+    const result = await this.#provider.search({
+      search_queries: input.search_queries,
+      objective: input.objective
+    });
+    return (0, import_IMCPServer.toolResultResponse)({ text: JSON.stringify(result) });
+  }
+  async runFetch(input) {
+    const result = await this.#provider.fetch({
+      urls: input.urls,
+      objective: input.objective
+    });
+    return (0, import_IMCPServer.toolResultResponse)({ text: JSON.stringify(result) });
+  }
+};
+function webSearch(options) {
+  return {
+    systemToolSets: [new WebSearchTools(options)],
+    instructionBuilders: [buildWebSearchInstruction]
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WEB_FETCH_TOOL_NAME,
+  WEB_SEARCH_REMINDER_TAG,
+  WEB_SEARCH_SERVER_ID,
+  WEB_SEARCH_TOOL_NAME,
+  WebSearchTools,
+  buildWebSearchInstruction,
+  webSearch
+});
+//# sourceMappingURL=WebSearch.js.map

package/dist/core/capabilities/builtins/WebSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/core/capabilities/builtins/WebSearch.ts"],"sourcesContent":["import dedent from 'dedent';\nimport { z } from 'zod';\nimport { InstructionBuilder } from '../../InstructionBuilder';\nimport { type CallToolResponse, toolResultResponse } from '../../mcp/IMCPServer';\nimport { defineTool, LocalToolMCP, type ToolDefinition } from '../../mcp/LocalToolMCP';\nimport type { AgentTracing } from '../../tracing/AgentTracing';\nimport type { IWebSearchProvider } from '../../web-search/WebSearchProvider';\nimport type { AgentCapability } from '../AgentCapability';\n\nexport const WEB_SEARCH_SERVER_ID = 'web-search';\nexport const WEB_SEARCH_TOOL_NAME = 'web_search';\nexport const WEB_FETCH_TOOL_NAME = 'web_fetch';\nexport const WEB_SEARCH_REMINDER_TAG = 'web-search';\n\nconst webSearchInputSchema = z\n  .object({\n    search_queries: z\n      .array(z.string().min(1))\n      .min(1)\n      .max(5)\n      .describe(\n        'Keyword search queries (prefer 3–6 words each; 2–3 queries often beat one long query). Operators such as site:domain, filetype:pdf, intitle:word, -term, and \"exact phrase\" may work when the backend supports them.',\n      ),\n    objective: z\n      .string()\n      .min(1)\n      .optional()\n      .describe('Natural-language goal for the search. Helps the backend focus hits when provided.'),\n  })\n  .strict();\n\nconst webFetchInputSchema = z\n  .object({\n    urls: z\n      .array(z.url())\n      .min(1)\n      .max(5)\n      .describe('Page URLs to extract (up to 5). Prefer specific hit URLs from web_search.'),\n    objective: z\n      .string()\n      .min(1)\n      .optional()\n      .describe('Optional goal used to focus extracted excerpts when the page is large.'),\n  })\n  .strict();\n\n/** What the tool does — param details live on the Zod schema `.describe`s. */\nconst WEB_SEARCH_TOOL_DESCRIPTION =\n  'Search the web. Returns ranked hits with titles, URLs, and snippets. Prefer concise keyword queries; use multiple related queries in one call when useful.';\n\n/** What the tool does — param details live on the Zod schema `.describe`s. */\nconst WEB_FETCH_TOOL_DESCRIPTION = `Extract page content from URLs as markdown/text (no LLM summarization). Prefer specific hit URLs from ${WEB_SEARCH_TOOL_NAME} when snippets are not enough.`;\n\n/**\n * Cross-tool policy (when / how to combine search + fetch).\n * Per-tool behavior and params stay on tool descriptions / schema describes.\n */\nexport function buildWebSearchInstruction(builder: InstructionBuilder): void {\n  builder.addSection(\n    WEB_SEARCH_REMINDER_TAG,\n    dedent`\n      The Agent has two system tools for live web access: ${WEB_SEARCH_TOOL_NAME} (search) and ${WEB_FETCH_TOOL_NAME} (extract page content).\n\n      When to use them:\n      - The user asks to search, browse, verify, look up, or get latest information.\n      - Facts may have changed recently (news, prices, laws, schedules, product specs, software APIs/docs, people in roles, rates, scores).\n      - The answer needs direct quotes, links, or precise source attribution.\n      - A specific page, paper, dataset, or site is referenced and its contents were not provided.\n\n      How to use them:\n      - Start with ${WEB_SEARCH_TOOL_NAME} for discovery; follow with ${WEB_FETCH_TOOL_NAME} on the best URLs when snippets are not enough.\n      - Prefer primary and authoritative sources.\n    `.trim(),\n  );\n}\n\nexport class WebSearchTools extends LocalToolMCP {\n  readonly name = WEB_SEARCH_SERVER_ID;\n  readonly displayName = 'WebSearch';\n  readonly #provider: IWebSearchProvider;\n\n  constructor(options: { provider: IWebSearchProvider; tracing: AgentTracing }) {\n    super({ tracing: options.tracing });\n    this.#provider = options.provider;\n  }\n\n  private tools: ToolDefinition[] = [\n    defineTool({\n      name: WEB_SEARCH_TOOL_NAME,\n      description: WEB_SEARCH_TOOL_DESCRIPTION,\n      schema: webSearchInputSchema,\n      handler: input => this.runSearch(input),\n    }),\n    defineTool({\n      name: WEB_FETCH_TOOL_NAME,\n      description: WEB_FETCH_TOOL_DESCRIPTION,\n      schema: webFetchInputSchema,\n      handler: input => this.runFetch(input),\n    }),\n  ];\n\n  protected getTools(): ToolDefinition[] {\n    return this.tools;\n  }\n\n  private async runSearch(input: z.infer<typeof webSearchInputSchema>): Promise<CallToolResponse> {\n    const result = await this.#provider.search({\n      search_queries: input.search_queries,\n      objective: input.objective,\n    });\n    return toolResultResponse({ text: JSON.stringify(result) });\n  }\n\n  private async runFetch(input: z.infer<typeof webFetchInputSchema>): Promise<CallToolResponse> {\n    const result = await this.#provider.fetch({\n      urls: input.urls,\n      objective: input.objective,\n    });\n    return toolResultResponse({ text: JSON.stringify(result) });\n  }\n}\n\nexport function webSearch(options: { provider: IWebSearchProvider; tracing: AgentTracing }): AgentCapability {\n  return {\n    systemToolSets: [new WebSearchTools(options)],\n    instructionBuilders: [buildWebSearchInstruction],\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAAmB;AACnB,iBAAkB;AAClB,gCAAmC;AACnC,wBAA0D;AAC1D,0BAA8D;AAKvD,IAAM,uBAAuB;AAC7B,IAAM,uBAAuB;AAC7B,IAAM,sBAAsB;AAC5B,IAAM,0BAA0B;AAEvC,IAAM,uBAAuB,aAC1B,OAAO;AAAA,EACN,gBAAgB,aACb,MAAM,aAAE,OAAO,EAAE,IAAI,CAAC,CAAC,EACvB,IAAI,CAAC,EACL,IAAI,CAAC,EACL;AAAA,IACC;AAAA,EACF;AAAA,EACF,WAAW,aACR,OAAO,EACP,IAAI,CAAC,EACL,SAAS,EACT,SAAS,mFAAmF;AACjG,CAAC,EACA,OAAO;AAEV,IAAM,sBAAsB,aACzB,OAAO;AAAA,EACN,MAAM,aACH,MAAM,aAAE,IAAI,CAAC,EACb,IAAI,CAAC,EACL,IAAI,CAAC,EACL,SAAS,2EAA2E;AAAA,EACvF,WAAW,aACR,OAAO,EACP,IAAI,CAAC,EACL,SAAS,EACT,SAAS,wEAAwE;AACtF,CAAC,EACA,OAAO;AAGV,IAAM,8BACJ;AAGF,IAAM,6BAA6B,yGAAyG,oBAAoB;AAMzJ,SAAS,0BAA0B,SAAmC;AAC3E,UAAQ;AAAA,IACN;AAAA,IACA,cAAAA;AAAA,4DACwD,oBAAoB,iBAAiB,mBAAmB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAS/F,oBAAoB,+BAA+B,mBAAmB;AAAA;AAAA,MAErF,KAAK;AAAA,EACT;AACF;AAEO,IAAM,iBAAN,cAA6B,iCAAa;AAAA,EACtC,OAAO;AAAA,EACP,cAAc;AAAA,EACd;AAAA,EAET,YAAY,SAAkE;AAC5E,UAAM,EAAE,SAAS,QAAQ,QAAQ,CAAC;AAClC,SAAK,YAAY,QAAQ;AAAA,EAC3B;AAAA,EAEQ,QAA0B;AAAA,QAChC,gCAAW;AAAA,MACT,MAAM;AAAA,MACN,aAAa;AAAA,MACb,QAAQ;AAAA,MACR,SAAS,WAAS,KAAK,UAAU,KAAK;AAAA,IACxC,CAAC;AAAA,QACD,gCAAW;AAAA,MACT,MAAM;AAAA,MACN,aAAa;AAAA,MACb,QAAQ;AAAA,MACR,SAAS,WAAS,KAAK,SAAS,KAAK;AAAA,IACvC,CAAC;AAAA,EACH;AAAA,EAEU,WAA6B;AACrC,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,MAAc,UAAU,OAAwE;AAC9F,UAAM,SAAS,MAAM,KAAK,UAAU,OAAO;AAAA,MACzC,gBAAgB,MAAM;AAAA,MACtB,WAAW,MAAM;AAAA,IACnB,CAAC;AACD,eAAO,sCAAmB,EAAE,MAAM,KAAK,UAAU,MAAM,EAAE,CAAC;AAAA,EAC5D;AAAA,EAEA,MAAc,SAAS,OAAuE;AAC5F,UAAM,SAAS,MAAM,KAAK,UAAU,MAAM;AAAA,MACxC,MAAM,MAAM;AAAA,MACZ,WAAW,MAAM;AAAA,IACnB,CAAC;AACD,eAAO,sCAAmB,EAAE,MAAM,KAAK,UAAU,MAAM,EAAE,CAAC;AAAA,EAC5D;AACF;AAEO,SAAS,UAAU,SAAmF;AAC3G,SAAO;AAAA,IACL,gBAAgB,CAAC,IAAI,eAAe,OAAO,CAAC;AAAA,IAC5C,qBAAqB,CAAC,yBAAyB;AAAA,EACjD;AACF;","names":["dedent"]}

package/dist/core/capabilities/builtins/WebSearch.mjs

@@ -0,0 +1,96 @@
+// src/core/capabilities/builtins/WebSearch.ts
+import dedent from "dedent";
+import { z } from "zod";
+import "../../InstructionBuilder.mjs";
+import { toolResultResponse } from "../../mcp/IMCPServer.mjs";
+import { defineTool, LocalToolMCP } from "../../mcp/LocalToolMCP.mjs";
+var WEB_SEARCH_SERVER_ID = "web-search";
+var WEB_SEARCH_TOOL_NAME = "web_search";
+var WEB_FETCH_TOOL_NAME = "web_fetch";
+var WEB_SEARCH_REMINDER_TAG = "web-search";
+var webSearchInputSchema = z.object({
+  search_queries: z.array(z.string().min(1)).min(1).max(5).describe(
+    'Keyword search queries (prefer 3\u20136 words each; 2\u20133 queries often beat one long query). Operators such as site:domain, filetype:pdf, intitle:word, -term, and "exact phrase" may work when the backend supports them.'
+  ),
+  objective: z.string().min(1).optional().describe("Natural-language goal for the search. Helps the backend focus hits when provided.")
+}).strict();
+var webFetchInputSchema = z.object({
+  urls: z.array(z.url()).min(1).max(5).describe("Page URLs to extract (up to 5). Prefer specific hit URLs from web_search."),
+  objective: z.string().min(1).optional().describe("Optional goal used to focus extracted excerpts when the page is large.")
+}).strict();
+var WEB_SEARCH_TOOL_DESCRIPTION = "Search the web. Returns ranked hits with titles, URLs, and snippets. Prefer concise keyword queries; use multiple related queries in one call when useful.";
+var WEB_FETCH_TOOL_DESCRIPTION = `Extract page content from URLs as markdown/text (no LLM summarization). Prefer specific hit URLs from ${WEB_SEARCH_TOOL_NAME} when snippets are not enough.`;
+function buildWebSearchInstruction(builder) {
+  builder.addSection(
+    WEB_SEARCH_REMINDER_TAG,
+    dedent`
+      The Agent has two system tools for live web access: ${WEB_SEARCH_TOOL_NAME} (search) and ${WEB_FETCH_TOOL_NAME} (extract page content).
+
+      When to use them:
+      - The user asks to search, browse, verify, look up, or get latest information.
+      - Facts may have changed recently (news, prices, laws, schedules, product specs, software APIs/docs, people in roles, rates, scores).
+      - The answer needs direct quotes, links, or precise source attribution.
+      - A specific page, paper, dataset, or site is referenced and its contents were not provided.
+
+      How to use them:
+      - Start with ${WEB_SEARCH_TOOL_NAME} for discovery; follow with ${WEB_FETCH_TOOL_NAME} on the best URLs when snippets are not enough.
+      - Prefer primary and authoritative sources.
+    `.trim()
+  );
+}
+var WebSearchTools = class extends LocalToolMCP {
+  name = WEB_SEARCH_SERVER_ID;
+  displayName = "WebSearch";
+  #provider;
+  constructor(options) {
+    super({ tracing: options.tracing });
+    this.#provider = options.provider;
+  }
+  tools = [
+    defineTool({
+      name: WEB_SEARCH_TOOL_NAME,
+      description: WEB_SEARCH_TOOL_DESCRIPTION,
+      schema: webSearchInputSchema,
+      handler: (input) => this.runSearch(input)
+    }),
+    defineTool({
+      name: WEB_FETCH_TOOL_NAME,
+      description: WEB_FETCH_TOOL_DESCRIPTION,
+      schema: webFetchInputSchema,
+      handler: (input) => this.runFetch(input)
+    })
+  ];
+  getTools() {
+    return this.tools;
+  }
+  async runSearch(input) {
+    const result = await this.#provider.search({
+      search_queries: input.search_queries,
+      objective: input.objective
+    });
+    return toolResultResponse({ text: JSON.stringify(result) });
+  }
+  async runFetch(input) {
+    const result = await this.#provider.fetch({
+      urls: input.urls,
+      objective: input.objective
+    });
+    return toolResultResponse({ text: JSON.stringify(result) });
+  }
+};
+function webSearch(options) {
+  return {
+    systemToolSets: [new WebSearchTools(options)],
+    instructionBuilders: [buildWebSearchInstruction]
+  };
+}
+export {
+  WEB_FETCH_TOOL_NAME,
+  WEB_SEARCH_REMINDER_TAG,
+  WEB_SEARCH_SERVER_ID,
+  WEB_SEARCH_TOOL_NAME,
+  WebSearchTools,
+  buildWebSearchInstruction,
+  webSearch
+};
+//# sourceMappingURL=WebSearch.mjs.map