experimental-agent 0.0.5 → 0.1.2

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 (40) hide show
  1. package/dist/agent-workflow.d.mts +1 -1
  2. package/dist/agent-workflow.d.ts +1 -1
  3. package/dist/agent-workflow.js +230 -139
  4. package/dist/agent-workflow.mjs +2 -2
  5. package/dist/{chunk-GJETDXOU.mjs → chunk-2SPAJ777.mjs} +5 -1
  6. package/dist/chunk-6J462JGP.mjs +1267 -0
  7. package/dist/{chunk-3ODWQVIA.mjs → chunk-BJTO5JO5.mjs} +1 -2
  8. package/dist/{chunk-CRDAPJEY.mjs → chunk-E7TOPGHY.mjs} +3 -3
  9. package/dist/chunk-ILPVXRI5.mjs +2026 -0
  10. package/dist/chunk-ORE6LK2L.mjs +344 -0
  11. package/dist/chunk-W4SSZPDX.mjs +106 -0
  12. package/dist/{client-9A8NO6x9.d.mts → client-CKLwB-ES.d.mts} +118 -15
  13. package/dist/{client-9A8NO6x9.d.ts → client-CKLwB-ES.d.ts} +118 -15
  14. package/dist/{client-5C4CNU6H.mjs → client-YUU54ZZH.mjs} +2 -2
  15. package/dist/client.mjs +1 -1
  16. package/dist/{handler-SZDTM3MC.mjs → handler-LDFBSCRA.mjs} +2 -2
  17. package/dist/index.d.mts +2 -2
  18. package/dist/index.d.ts +2 -2
  19. package/dist/index.js +333 -171
  20. package/dist/index.mjs +68 -32
  21. package/dist/lifecycle-workflow.d.mts +1 -1
  22. package/dist/lifecycle-workflow.d.ts +1 -1
  23. package/dist/lifecycle-workflow.js +18 -1
  24. package/dist/lifecycle-workflow.mjs +2 -2
  25. package/dist/local-fs-handlers-SY2RDXZE.mjs +314 -0
  26. package/dist/next/loader.js +6 -6
  27. package/dist/next/loader.mjs +3 -3
  28. package/dist/next.js +3 -3
  29. package/dist/next.mjs +5 -5
  30. package/dist/{process-manager-JAKAXROL.mjs → process-manager-ZCET3VD2.mjs} +1 -1
  31. package/dist/{sandbox-M24R3JLM.mjs → sandbox-GPCA35PJ.mjs} +3 -3
  32. package/dist/{storage-TMZQJ2OQ.mjs → storage-LL6IA24R.mjs} +3 -3
  33. package/dist/{vercel-WGN2NY3D.mjs → vercel-SD3JTECG.mjs} +1 -1
  34. package/dist/{vercel-sdk-UKBD5JDI.mjs → vercel-sdk-I6A4MVAN.mjs} +1 -1
  35. package/package.json +2 -2
  36. package/dist/chunk-2IIWVPZB.mjs +0 -334
  37. package/dist/chunk-CQB6AOJ7.mjs +0 -103
  38. package/dist/chunk-M2XPBOZD.mjs +0 -1980
  39. package/dist/chunk-ZWP7RQZT.mjs +0 -1239
  40. package/dist/local-fs-handlers-BZVA3XAU.mjs +0 -277
@@ -1,6 +1,6 @@
1
1
  import * as errore from 'errore';
2
2
  import * as ai from 'ai';
3
- import { UIMessage, JSONSchema7, ToolSet, InferToolInput, ModelMessage, GatewayModelId, UIDataTypes, InferUITools, UIMessageChunk } from 'ai';
3
+ import { UIMessage, JSONSchema7, ToolSet, InferToolInput, ModelMessage, GatewayModelId, UIMessageChunk, InferUITools } from 'ai';
4
4
  import { z } from 'zod';
5
5
 
6
6
  declare const SessionNotFoundError_base: errore.FactoryTaggedErrorClass<"SessionNotFoundError", "Session $id not found", Error>;
@@ -432,6 +432,12 @@ declare const methods: {
432
432
  nextCursor: z.ZodNullable<z.ZodString>;
433
433
  }, z.core.$strip>;
434
434
  };
435
+ readonly "session.delete": {
436
+ readonly params: z.ZodObject<{
437
+ id: z.ZodString;
438
+ }, z.core.$strip>;
439
+ readonly result: z.ZodVoid;
440
+ };
435
441
  readonly "session.tag.set": {
436
442
  readonly params: z.ZodObject<{
437
443
  sessionId: z.ZodString;
@@ -1265,10 +1271,39 @@ type ListResult<T> = {
1265
1271
  items: T[];
1266
1272
  nextCursor: string | null;
1267
1273
  };
1274
+ /**
1275
+ * Session with tags narrowed to a specific schema.
1276
+ */
1277
+ type TypedSession<TTags extends Record<string, unknown>> = Omit<Session, "tags"> & {
1278
+ tags: Partial<TTags> | null;
1279
+ };
1280
+ /**
1281
+ * Storage interface with session tags narrowed to the agent's tagsSchema.
1282
+ * Used by the agent's `storage` getter so callers get typed tags on sessions.
1283
+ */
1284
+ type TypedStorage<TTags extends Record<string, unknown>> = Omit<Storage, "session"> & {
1285
+ session: Omit<Storage["session"], "get" | "set" | "list" | "tag"> & {
1286
+ get: (id: string) => Promise<SessionNotFoundError | StorageError | TypedSession<TTags>>;
1287
+ set: (session: TypedSession<TTags>) => Promise<StorageError | TypedSession<TTags>>;
1288
+ list: (opts?: {
1289
+ tags?: Partial<TTags>;
1290
+ order?: "createdAt_asc" | "createdAt_desc" | "updatedAt_asc" | "updatedAt_desc";
1291
+ cursor?: string;
1292
+ limit?: number;
1293
+ }) => Promise<StorageError | ListResult<TypedSession<TTags>>>;
1294
+ tag: {
1295
+ set: (opts: {
1296
+ sessionId: string;
1297
+ tags: Partial<TTags>;
1298
+ }) => Promise<StorageError | TypedSession<TTags>>;
1299
+ };
1300
+ };
1301
+ };
1268
1302
  interface Storage {
1269
1303
  session: {
1270
1304
  get: (id: string) => Promise<SessionNotFoundError | StorageError | Session>;
1271
1305
  set: (session: Session) => Promise<StorageError | Session>;
1306
+ delete: (id: string) => Promise<StorageError | undefined>;
1272
1307
  list: (opts?: {
1273
1308
  tags?: Record<string, unknown>;
1274
1309
  order?: "createdAt_asc" | "createdAt_desc" | "updatedAt_asc" | "updatedAt_desc";
@@ -1407,7 +1442,7 @@ type SandboxLifecycleInput = {
1407
1442
  id: string;
1408
1443
  vercelSandboxId: string;
1409
1444
  storageConfig: StorageConfig;
1410
- rpc: RpcFn;
1445
+ rpc?: RpcFn;
1411
1446
  };
1412
1447
  type LogEntry = {
1413
1448
  stream: "stdout" | "stderr";
@@ -1483,6 +1518,19 @@ interface Sandbox<TTags extends TagsSchema = TagsSchema> {
1483
1518
  };
1484
1519
  }
1485
1520
 
1521
+ /**
1522
+ * Metadata about how the sandbox was set up.
1523
+ * Used by the workflow to emit the correct status indicator.
1524
+ * Returned as a promise because the metadata is determined asynchronously
1525
+ * during sandbox creation, before _onReady runs setup.
1526
+ */
1527
+ type SandboxSetupMeta = {
1528
+ /** Whether setup.run() needs to execute (cold start, no snapshot). */
1529
+ needsSetupRun: boolean;
1530
+ /** Whether the sandbox was created from a snapshot. */
1531
+ createdFromSnapshot: boolean;
1532
+ };
1533
+
1486
1534
  type GenerationOptions = {
1487
1535
  /** Max tool-use steps per assistant response. Default: unlimited. */
1488
1536
  maxSteps?: number;
@@ -1627,6 +1675,10 @@ type ToolsNeedsApprovalParams = {
1627
1675
  messages: unknown[];
1628
1676
  };
1629
1677
  type ToolsNeedsApprovalResult = boolean;
1678
+ type HookStatusParams = {
1679
+ status: AgentStatus;
1680
+ };
1681
+ type HookStatusResult = Record<string, never>;
1630
1682
 
1631
1683
  type SessionUsage = {
1632
1684
  total: UsageSummary & {
@@ -1640,20 +1692,57 @@ type SendInput = string | {
1640
1692
  parts: UIMessage["parts"];
1641
1693
  id?: string;
1642
1694
  };
1695
+ /**
1696
+ * Transient status indicators emitted over the stream during long-running phases.
1697
+ * Delivered to the client as `data-status` chunks with `transient: true` — not persisted.
1698
+ */
1699
+ type AgentStatus = {
1700
+ type: "sandbox-setup";
1701
+ } | {
1702
+ type: "sandbox-setup-cold";
1703
+ } | {
1704
+ type: "loading-skills";
1705
+ } | {
1706
+ type: "processing-approvals";
1707
+ } | {
1708
+ type: "needs-approval";
1709
+ } | {
1710
+ type: "thinking";
1711
+ } | {
1712
+ type: "custom";
1713
+ status: string;
1714
+ };
1715
+ /**
1716
+ * Augmented `ReadableStream` returned by `session.stream()`.
1717
+ * Passes `instanceof ReadableStream` and works with `createUIMessageStreamResponse({ stream })`.
1718
+ */
1719
+ type AgentStream = ReadableStream<UIMessageChunk> & {
1720
+ /** Write a typed status update to the stream (transient, not persisted). */
1721
+ writeStatus: (status: AgentStatus) => void;
1722
+ };
1723
+ /**
1724
+ * Data part types emitted by every agent over the stream.
1725
+ * Used as the `DATA_PARTS` generic for `UIMessage`.
1726
+ */
1727
+ type AgentDataTypes = {
1728
+ status: AgentStatus;
1729
+ };
1643
1730
  /**
1644
1731
  * Infer a typed UIMessage from an agent instance.
1645
1732
  * Tool parts are discriminated by `type: "tool-${name}"` with typed input/output.
1733
+ * Data parts include `data-status` with typed `AgentStatus`.
1646
1734
  *
1647
1735
  * @example
1648
1736
  * ```ts
1649
1737
  * const myAgent = agent({ tools: { myTool: tool({...}) } });
1650
- * type MyMessage = InferUIMessage<typeof myAgent>;
1738
+ * type MyMessage = typeof myAgent.$UIMessage;
1651
1739
  * // MyMessage.parts includes { type: "tool-myTool"; input: MyInput; output: MyOutput; ... }
1740
+ * // onData callback receives { type: "data-status"; data: AgentStatus }
1652
1741
  * ```
1653
1742
  */
1654
1743
  type InferUIMessage<A> = A extends {
1655
1744
  tools: infer T extends ToolSet;
1656
- } ? UIMessage<unknown, UIDataTypes, InferUITools<T>> : UIMessage;
1745
+ } ? UIMessage<unknown, AgentDataTypes, InferUITools<T>> : UIMessage<unknown, AgentDataTypes>;
1657
1746
  type ToolName<Tools> = Extract<keyof Tools, string> | BuiltInToolName;
1658
1747
  type ToolInput<Tools, K> = K extends BuiltInToolName ? InferToolInput<(typeof builtInTools)[K]> : K extends keyof Tools ? Tools[K] extends ai.Tool ? InferToolInput<Tools[K]> : unknown : unknown;
1659
1748
  type NeedsApprovalMap<Tools> = {
@@ -1689,10 +1778,6 @@ type SessionOptions<Tools extends ToolSet, TTags extends Record<string, unknown>
1689
1778
  /** Generation options (temperature, maxSteps, etc.). Overrides agent-level defaults. */
1690
1779
  generation?: GenerationOptions;
1691
1780
  };
1692
- /**
1693
- * Fields that can be updated on an existing session via `session.update()`.
1694
- * Excludes sandbox (not changeable after creation) and tags (use `session.tag` methods).
1695
- */
1696
1781
  type SessionUpdateOptions<Tools extends ToolSet> = Pick<SessionOptions<Tools>, "model" | "system" | "skillsDir" | "activeTools" | "generation">;
1697
1782
  /**
1698
1783
  * Configuration options for creating an agent instance.
@@ -1807,6 +1892,8 @@ type AgentHooks = {
1807
1892
  }) => Promise<undefined | {
1808
1893
  result: unknown;
1809
1894
  }>;
1895
+ /** Called when the agent emits a transient status indicator. */
1896
+ status?: (status: AgentStatus) => void | Promise<void>;
1810
1897
  };
1811
1898
  /**
1812
1899
  * RPC response type for dispatch.
@@ -1853,6 +1940,10 @@ type AgentRpcMethods = {
1853
1940
  params: HookToolAfterParams;
1854
1941
  result: HookToolAfterResult;
1855
1942
  };
1943
+ "hook.status": {
1944
+ params: HookStatusParams;
1945
+ result: HookStatusResult;
1946
+ };
1856
1947
  } & StorageMethods;
1857
1948
  type AgentRpcMethodName = keyof AgentRpcMethods;
1858
1949
  /**
@@ -1885,9 +1976,9 @@ declare const agent: <Tools extends {}, TTags extends Record<string, unknown> =
1885
1976
  }) => Promise<void | SessionError | StorageError>;
1886
1977
  stream: (opts?: {
1887
1978
  messageId?: string;
1888
- }) => Promise<SessionNotFoundError | SessionError | StorageError | ReadableStream<UIMessageChunk>>;
1979
+ }) => Promise<AgentStream | Error>;
1889
1980
  ui: () => Promise<StorageError | {
1890
- messages: UIMessage<unknown, UIDataTypes, InferUITools<{
1981
+ messages: UIMessage<unknown, AgentDataTypes, InferUITools<{
1891
1982
  Read: ai.Tool<{
1892
1983
  path: string;
1893
1984
  startLine?: number | undefined;
@@ -1980,7 +2071,10 @@ declare const agent: <Tools extends {}, TTags extends Record<string, unknown> =
1980
2071
  set: <K extends keyof TTags & string>(key: K, value: TTags[K]) => Promise<undefined | Error>;
1981
2072
  setMany: (tags: Partial<TTags>) => Promise<undefined | Error>;
1982
2073
  };
1983
- sandbox: Sandbox<TTags>;
2074
+ sandbox: Sandbox<TTags> & {
2075
+ _onReady?: Promise<void>;
2076
+ _setupMeta?: Promise<SandboxSetupMeta>;
2077
+ };
1984
2078
  interrupt: () => Promise<StorageError | undefined>;
1985
2079
  resolveApproval: ({ approvalId, approved, reason, }: {
1986
2080
  approvalId: string;
@@ -1988,15 +2082,20 @@ declare const agent: <Tools extends {}, TTags extends Record<string, unknown> =
1988
2082
  reason?: string;
1989
2083
  }) => Promise<undefined | Error>;
1990
2084
  usage: () => Promise<SessionUsage | Error>;
1991
- update: (updateOptions: SessionUpdateOptions<Tools>) => Promise<undefined | Error>;
2085
+ update: (updateOptions: SessionUpdateOptions<Tools> & {
2086
+ tags?: TTags;
2087
+ }) => Promise<undefined | Error>;
1992
2088
  }>;
1993
2089
  sandbox: (sandboxId: string, opts?: {
1994
2090
  config?: SandboxConfig;
1995
2091
  tags?: TTags;
1996
2092
  setup?: SandboxSetup;
1997
2093
  onRestart?: OnRestart;
1998
- }) => Promise<Sandbox<TTags>>;
1999
- readonly storage: Storage;
2094
+ }) => Promise<Sandbox<TTags> & {
2095
+ _onReady?: Promise<void>;
2096
+ _setupMeta?: Promise<SandboxSetupMeta>;
2097
+ }>;
2098
+ readonly storage: TypedStorage<TTags>;
2000
2099
  /**
2001
2100
  * RPC handler for agent operations.
2002
2101
  * Handles tools.list, tools.execute, storage RPC, and hooks.
@@ -2006,7 +2105,11 @@ declare const agent: <Tools extends {}, TTags extends Record<string, unknown> =
2006
2105
  */
2007
2106
  handler: (input: Request | RpcPayload, overrides?: AgentRpcOverrides) => Promise<Response | RpcResult>;
2008
2107
  tools: typeof builtInTools & Tools;
2108
+ /** Phantom property for type inference. Use `typeof myAgent.$UIMessage` to get the typed UIMessage. */
2109
+ $UIMessage: UIMessage<unknown, AgentDataTypes, InferUITools<typeof builtInTools & Tools>>;
2110
+ /** Agent name used as key for the RPC registry. Set by the loader init. */
2111
+ _agentName: string;
2009
2112
  rpc: (params: RpcPayload) => Promise<RpcResult>;
2010
2113
  };
2011
2114
 
2012
- export { type AgentOptions as A, type BuiltInToolName as B, type ExecResult as E, type GenerationOptions as G, type InferUIMessage as I, type ListResult as L, type MethodName as M, type OnRestart as O, type Part as P, type ResolvedStorage as R, type StorageMethods as S, type TagsSchema as T, type UploadableFile as U, type Message as a, MessageNotFoundError as b, type MessageUsage as c, type RpcPayload as d, type RpcResult as e, type Sandbox as f, type SandboxConfig as g, SandboxError as h, SandboxNotFoundError as i, type SandboxRecord as j, type SandboxSetup as k, type SendInput as l, type Session as m, SessionNotFoundError as n, type SessionOptions as o, type SkillSummary as p, type StepUsage as q, type StorageConfig as r, StorageError as s, type ToolContext as t, type UsageSummary as u, agent as v, builtinToolNames as w, type SandboxLifecycleInput as x };
2115
+ export { type AgentDataTypes as A, type BuiltInToolName as B, type SandboxLifecycleInput as C, type ExecResult as E, type GenerationOptions as G, type InferUIMessage as I, type ListResult as L, type MethodName as M, type OnRestart as O, type Part as P, type ResolvedStorage as R, type StorageMethods as S, type TagsSchema as T, type UploadableFile as U, type AgentOptions as a, type AgentStatus as b, type AgentStream as c, type Message as d, MessageNotFoundError as e, type MessageUsage as f, type RpcPayload as g, type RpcResult as h, type Sandbox as i, type SandboxConfig as j, SandboxError as k, SandboxNotFoundError as l, type SandboxRecord as m, type SandboxSetup as n, type SendInput as o, type Session as p, SessionNotFoundError as q, type SessionOptions as r, type SkillSummary as s, type StepUsage as t, type StorageConfig as u, StorageError as v, type ToolContext as w, type UsageSummary as x, agent as y, builtinToolNames as z };
@@ -1,6 +1,6 @@
1
1
  import * as errore from 'errore';
2
2
  import * as ai from 'ai';
3
- import { UIMessage, JSONSchema7, ToolSet, InferToolInput, ModelMessage, GatewayModelId, UIDataTypes, InferUITools, UIMessageChunk } from 'ai';
3
+ import { UIMessage, JSONSchema7, ToolSet, InferToolInput, ModelMessage, GatewayModelId, UIMessageChunk, InferUITools } from 'ai';
4
4
  import { z } from 'zod';
5
5
 
6
6
  declare const SessionNotFoundError_base: errore.FactoryTaggedErrorClass<"SessionNotFoundError", "Session $id not found", Error>;
@@ -432,6 +432,12 @@ declare const methods: {
432
432
  nextCursor: z.ZodNullable<z.ZodString>;
433
433
  }, z.core.$strip>;
434
434
  };
435
+ readonly "session.delete": {
436
+ readonly params: z.ZodObject<{
437
+ id: z.ZodString;
438
+ }, z.core.$strip>;
439
+ readonly result: z.ZodVoid;
440
+ };
435
441
  readonly "session.tag.set": {
436
442
  readonly params: z.ZodObject<{
437
443
  sessionId: z.ZodString;
@@ -1265,10 +1271,39 @@ type ListResult<T> = {
1265
1271
  items: T[];
1266
1272
  nextCursor: string | null;
1267
1273
  };
1274
+ /**
1275
+ * Session with tags narrowed to a specific schema.
1276
+ */
1277
+ type TypedSession<TTags extends Record<string, unknown>> = Omit<Session, "tags"> & {
1278
+ tags: Partial<TTags> | null;
1279
+ };
1280
+ /**
1281
+ * Storage interface with session tags narrowed to the agent's tagsSchema.
1282
+ * Used by the agent's `storage` getter so callers get typed tags on sessions.
1283
+ */
1284
+ type TypedStorage<TTags extends Record<string, unknown>> = Omit<Storage, "session"> & {
1285
+ session: Omit<Storage["session"], "get" | "set" | "list" | "tag"> & {
1286
+ get: (id: string) => Promise<SessionNotFoundError | StorageError | TypedSession<TTags>>;
1287
+ set: (session: TypedSession<TTags>) => Promise<StorageError | TypedSession<TTags>>;
1288
+ list: (opts?: {
1289
+ tags?: Partial<TTags>;
1290
+ order?: "createdAt_asc" | "createdAt_desc" | "updatedAt_asc" | "updatedAt_desc";
1291
+ cursor?: string;
1292
+ limit?: number;
1293
+ }) => Promise<StorageError | ListResult<TypedSession<TTags>>>;
1294
+ tag: {
1295
+ set: (opts: {
1296
+ sessionId: string;
1297
+ tags: Partial<TTags>;
1298
+ }) => Promise<StorageError | TypedSession<TTags>>;
1299
+ };
1300
+ };
1301
+ };
1268
1302
  interface Storage {
1269
1303
  session: {
1270
1304
  get: (id: string) => Promise<SessionNotFoundError | StorageError | Session>;
1271
1305
  set: (session: Session) => Promise<StorageError | Session>;
1306
+ delete: (id: string) => Promise<StorageError | undefined>;
1272
1307
  list: (opts?: {
1273
1308
  tags?: Record<string, unknown>;
1274
1309
  order?: "createdAt_asc" | "createdAt_desc" | "updatedAt_asc" | "updatedAt_desc";
@@ -1407,7 +1442,7 @@ type SandboxLifecycleInput = {
1407
1442
  id: string;
1408
1443
  vercelSandboxId: string;
1409
1444
  storageConfig: StorageConfig;
1410
- rpc: RpcFn;
1445
+ rpc?: RpcFn;
1411
1446
  };
1412
1447
  type LogEntry = {
1413
1448
  stream: "stdout" | "stderr";
@@ -1483,6 +1518,19 @@ interface Sandbox<TTags extends TagsSchema = TagsSchema> {
1483
1518
  };
1484
1519
  }
1485
1520
 
1521
+ /**
1522
+ * Metadata about how the sandbox was set up.
1523
+ * Used by the workflow to emit the correct status indicator.
1524
+ * Returned as a promise because the metadata is determined asynchronously
1525
+ * during sandbox creation, before _onReady runs setup.
1526
+ */
1527
+ type SandboxSetupMeta = {
1528
+ /** Whether setup.run() needs to execute (cold start, no snapshot). */
1529
+ needsSetupRun: boolean;
1530
+ /** Whether the sandbox was created from a snapshot. */
1531
+ createdFromSnapshot: boolean;
1532
+ };
1533
+
1486
1534
  type GenerationOptions = {
1487
1535
  /** Max tool-use steps per assistant response. Default: unlimited. */
1488
1536
  maxSteps?: number;
@@ -1627,6 +1675,10 @@ type ToolsNeedsApprovalParams = {
1627
1675
  messages: unknown[];
1628
1676
  };
1629
1677
  type ToolsNeedsApprovalResult = boolean;
1678
+ type HookStatusParams = {
1679
+ status: AgentStatus;
1680
+ };
1681
+ type HookStatusResult = Record<string, never>;
1630
1682
 
1631
1683
  type SessionUsage = {
1632
1684
  total: UsageSummary & {
@@ -1640,20 +1692,57 @@ type SendInput = string | {
1640
1692
  parts: UIMessage["parts"];
1641
1693
  id?: string;
1642
1694
  };
1695
+ /**
1696
+ * Transient status indicators emitted over the stream during long-running phases.
1697
+ * Delivered to the client as `data-status` chunks with `transient: true` — not persisted.
1698
+ */
1699
+ type AgentStatus = {
1700
+ type: "sandbox-setup";
1701
+ } | {
1702
+ type: "sandbox-setup-cold";
1703
+ } | {
1704
+ type: "loading-skills";
1705
+ } | {
1706
+ type: "processing-approvals";
1707
+ } | {
1708
+ type: "needs-approval";
1709
+ } | {
1710
+ type: "thinking";
1711
+ } | {
1712
+ type: "custom";
1713
+ status: string;
1714
+ };
1715
+ /**
1716
+ * Augmented `ReadableStream` returned by `session.stream()`.
1717
+ * Passes `instanceof ReadableStream` and works with `createUIMessageStreamResponse({ stream })`.
1718
+ */
1719
+ type AgentStream = ReadableStream<UIMessageChunk> & {
1720
+ /** Write a typed status update to the stream (transient, not persisted). */
1721
+ writeStatus: (status: AgentStatus) => void;
1722
+ };
1723
+ /**
1724
+ * Data part types emitted by every agent over the stream.
1725
+ * Used as the `DATA_PARTS` generic for `UIMessage`.
1726
+ */
1727
+ type AgentDataTypes = {
1728
+ status: AgentStatus;
1729
+ };
1643
1730
  /**
1644
1731
  * Infer a typed UIMessage from an agent instance.
1645
1732
  * Tool parts are discriminated by `type: "tool-${name}"` with typed input/output.
1733
+ * Data parts include `data-status` with typed `AgentStatus`.
1646
1734
  *
1647
1735
  * @example
1648
1736
  * ```ts
1649
1737
  * const myAgent = agent({ tools: { myTool: tool({...}) } });
1650
- * type MyMessage = InferUIMessage<typeof myAgent>;
1738
+ * type MyMessage = typeof myAgent.$UIMessage;
1651
1739
  * // MyMessage.parts includes { type: "tool-myTool"; input: MyInput; output: MyOutput; ... }
1740
+ * // onData callback receives { type: "data-status"; data: AgentStatus }
1652
1741
  * ```
1653
1742
  */
1654
1743
  type InferUIMessage<A> = A extends {
1655
1744
  tools: infer T extends ToolSet;
1656
- } ? UIMessage<unknown, UIDataTypes, InferUITools<T>> : UIMessage;
1745
+ } ? UIMessage<unknown, AgentDataTypes, InferUITools<T>> : UIMessage<unknown, AgentDataTypes>;
1657
1746
  type ToolName<Tools> = Extract<keyof Tools, string> | BuiltInToolName;
1658
1747
  type ToolInput<Tools, K> = K extends BuiltInToolName ? InferToolInput<(typeof builtInTools)[K]> : K extends keyof Tools ? Tools[K] extends ai.Tool ? InferToolInput<Tools[K]> : unknown : unknown;
1659
1748
  type NeedsApprovalMap<Tools> = {
@@ -1689,10 +1778,6 @@ type SessionOptions<Tools extends ToolSet, TTags extends Record<string, unknown>
1689
1778
  /** Generation options (temperature, maxSteps, etc.). Overrides agent-level defaults. */
1690
1779
  generation?: GenerationOptions;
1691
1780
  };
1692
- /**
1693
- * Fields that can be updated on an existing session via `session.update()`.
1694
- * Excludes sandbox (not changeable after creation) and tags (use `session.tag` methods).
1695
- */
1696
1781
  type SessionUpdateOptions<Tools extends ToolSet> = Pick<SessionOptions<Tools>, "model" | "system" | "skillsDir" | "activeTools" | "generation">;
1697
1782
  /**
1698
1783
  * Configuration options for creating an agent instance.
@@ -1807,6 +1892,8 @@ type AgentHooks = {
1807
1892
  }) => Promise<undefined | {
1808
1893
  result: unknown;
1809
1894
  }>;
1895
+ /** Called when the agent emits a transient status indicator. */
1896
+ status?: (status: AgentStatus) => void | Promise<void>;
1810
1897
  };
1811
1898
  /**
1812
1899
  * RPC response type for dispatch.
@@ -1853,6 +1940,10 @@ type AgentRpcMethods = {
1853
1940
  params: HookToolAfterParams;
1854
1941
  result: HookToolAfterResult;
1855
1942
  };
1943
+ "hook.status": {
1944
+ params: HookStatusParams;
1945
+ result: HookStatusResult;
1946
+ };
1856
1947
  } & StorageMethods;
1857
1948
  type AgentRpcMethodName = keyof AgentRpcMethods;
1858
1949
  /**
@@ -1885,9 +1976,9 @@ declare const agent: <Tools extends {}, TTags extends Record<string, unknown> =
1885
1976
  }) => Promise<void | SessionError | StorageError>;
1886
1977
  stream: (opts?: {
1887
1978
  messageId?: string;
1888
- }) => Promise<SessionNotFoundError | SessionError | StorageError | ReadableStream<UIMessageChunk>>;
1979
+ }) => Promise<AgentStream | Error>;
1889
1980
  ui: () => Promise<StorageError | {
1890
- messages: UIMessage<unknown, UIDataTypes, InferUITools<{
1981
+ messages: UIMessage<unknown, AgentDataTypes, InferUITools<{
1891
1982
  Read: ai.Tool<{
1892
1983
  path: string;
1893
1984
  startLine?: number | undefined;
@@ -1980,7 +2071,10 @@ declare const agent: <Tools extends {}, TTags extends Record<string, unknown> =
1980
2071
  set: <K extends keyof TTags & string>(key: K, value: TTags[K]) => Promise<undefined | Error>;
1981
2072
  setMany: (tags: Partial<TTags>) => Promise<undefined | Error>;
1982
2073
  };
1983
- sandbox: Sandbox<TTags>;
2074
+ sandbox: Sandbox<TTags> & {
2075
+ _onReady?: Promise<void>;
2076
+ _setupMeta?: Promise<SandboxSetupMeta>;
2077
+ };
1984
2078
  interrupt: () => Promise<StorageError | undefined>;
1985
2079
  resolveApproval: ({ approvalId, approved, reason, }: {
1986
2080
  approvalId: string;
@@ -1988,15 +2082,20 @@ declare const agent: <Tools extends {}, TTags extends Record<string, unknown> =
1988
2082
  reason?: string;
1989
2083
  }) => Promise<undefined | Error>;
1990
2084
  usage: () => Promise<SessionUsage | Error>;
1991
- update: (updateOptions: SessionUpdateOptions<Tools>) => Promise<undefined | Error>;
2085
+ update: (updateOptions: SessionUpdateOptions<Tools> & {
2086
+ tags?: TTags;
2087
+ }) => Promise<undefined | Error>;
1992
2088
  }>;
1993
2089
  sandbox: (sandboxId: string, opts?: {
1994
2090
  config?: SandboxConfig;
1995
2091
  tags?: TTags;
1996
2092
  setup?: SandboxSetup;
1997
2093
  onRestart?: OnRestart;
1998
- }) => Promise<Sandbox<TTags>>;
1999
- readonly storage: Storage;
2094
+ }) => Promise<Sandbox<TTags> & {
2095
+ _onReady?: Promise<void>;
2096
+ _setupMeta?: Promise<SandboxSetupMeta>;
2097
+ }>;
2098
+ readonly storage: TypedStorage<TTags>;
2000
2099
  /**
2001
2100
  * RPC handler for agent operations.
2002
2101
  * Handles tools.list, tools.execute, storage RPC, and hooks.
@@ -2006,7 +2105,11 @@ declare const agent: <Tools extends {}, TTags extends Record<string, unknown> =
2006
2105
  */
2007
2106
  handler: (input: Request | RpcPayload, overrides?: AgentRpcOverrides) => Promise<Response | RpcResult>;
2008
2107
  tools: typeof builtInTools & Tools;
2108
+ /** Phantom property for type inference. Use `typeof myAgent.$UIMessage` to get the typed UIMessage. */
2109
+ $UIMessage: UIMessage<unknown, AgentDataTypes, InferUITools<typeof builtInTools & Tools>>;
2110
+ /** Agent name used as key for the RPC registry. Set by the loader init. */
2111
+ _agentName: string;
2009
2112
  rpc: (params: RpcPayload) => Promise<RpcResult>;
2010
2113
  };
2011
2114
 
2012
- export { type AgentOptions as A, type BuiltInToolName as B, type ExecResult as E, type GenerationOptions as G, type InferUIMessage as I, type ListResult as L, type MethodName as M, type OnRestart as O, type Part as P, type ResolvedStorage as R, type StorageMethods as S, type TagsSchema as T, type UploadableFile as U, type Message as a, MessageNotFoundError as b, type MessageUsage as c, type RpcPayload as d, type RpcResult as e, type Sandbox as f, type SandboxConfig as g, SandboxError as h, SandboxNotFoundError as i, type SandboxRecord as j, type SandboxSetup as k, type SendInput as l, type Session as m, SessionNotFoundError as n, type SessionOptions as o, type SkillSummary as p, type StepUsage as q, type StorageConfig as r, StorageError as s, type ToolContext as t, type UsageSummary as u, agent as v, builtinToolNames as w, type SandboxLifecycleInput as x };
2115
+ export { type AgentDataTypes as A, type BuiltInToolName as B, type SandboxLifecycleInput as C, type ExecResult as E, type GenerationOptions as G, type InferUIMessage as I, type ListResult as L, type MethodName as M, type OnRestart as O, type Part as P, type ResolvedStorage as R, type StorageMethods as S, type TagsSchema as T, type UploadableFile as U, type AgentOptions as a, type AgentStatus as b, type AgentStream as c, type Message as d, MessageNotFoundError as e, type MessageUsage as f, type RpcPayload as g, type RpcResult as h, type Sandbox as i, type SandboxConfig as j, SandboxError as k, SandboxNotFoundError as l, type SandboxRecord as m, type SandboxSetup as n, type SendInput as o, type Session as p, SessionNotFoundError as q, type SessionOptions as r, type SkillSummary as s, type StepUsage as t, type StorageConfig as u, StorageError as v, type ToolContext as w, type UsageSummary as x, agent as y, builtinToolNames as z };
@@ -3,9 +3,9 @@ import {
3
3
  LOCAL_STORAGE_VERSION,
4
4
  getStorage,
5
5
  getStorageClient
6
- } from "./chunk-2IIWVPZB.mjs";
6
+ } from "./chunk-ORE6LK2L.mjs";
7
7
  import "./chunk-HJGPUEFC.mjs";
8
- import "./chunk-3ODWQVIA.mjs";
8
+ import "./chunk-BJTO5JO5.mjs";
9
9
  export {
10
10
  DEFAULT_NAMESPACE,
11
11
  LOCAL_STORAGE_VERSION,
package/dist/client.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import "./chunk-3ODWQVIA.mjs";
1
+ import "./chunk-BJTO5JO5.mjs";
2
2
 
3
3
  // src/ui.ts
4
4
  function isToolPart(part) {
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  handleStorageRpc
3
- } from "./chunk-GJETDXOU.mjs";
4
- import "./chunk-3ODWQVIA.mjs";
3
+ } from "./chunk-2SPAJ777.mjs";
4
+ import "./chunk-BJTO5JO5.mjs";
5
5
  export {
6
6
  handleStorageRpc
7
7
  };
package/dist/index.d.mts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MethodName, S as StorageMethods } from './client-9A8NO6x9.mjs';
2
- export { A as AgentOptions, B as BuiltInToolName, E as ExecResult, G as GenerationOptions, I as InferUIMessage, L as ListResult, a as Message, b as MessageNotFoundError, c as MessageUsage, O as OnRestart, P as Part, R as ResolvedStorage, d as RpcPayload, e as RpcResult, f as Sandbox, g as SandboxConfig, h as SandboxError, i as SandboxNotFoundError, j as SandboxRecord, k as SandboxSetup, l as SendInput, m as Session, n as SessionNotFoundError, o as SessionOptions, p as SkillSummary, q as StepUsage, r as StorageConfig, s as StorageError, T as TagsSchema, t as ToolContext, U as UploadableFile, u as UsageSummary, v as agent, w as builtinToolNames } from './client-9A8NO6x9.mjs';
1
+ import { M as MethodName, S as StorageMethods } from './client-CKLwB-ES.mjs';
2
+ export { A as AgentDataTypes, a as AgentOptions, b as AgentStatus, c as AgentStream, B as BuiltInToolName, E as ExecResult, G as GenerationOptions, I as InferUIMessage, L as ListResult, d as Message, e as MessageNotFoundError, f as MessageUsage, O as OnRestart, P as Part, R as ResolvedStorage, g as RpcPayload, h as RpcResult, i as Sandbox, j as SandboxConfig, k as SandboxError, l as SandboxNotFoundError, m as SandboxRecord, n as SandboxSetup, o as SendInput, p as Session, q as SessionNotFoundError, r as SessionOptions, s as SkillSummary, t as StepUsage, u as StorageConfig, v as StorageError, T as TagsSchema, w as ToolContext, U as UploadableFile, x as UsageSummary, y as agent, z as builtinToolNames } from './client-CKLwB-ES.mjs';
3
3
  import { z } from 'zod';
4
4
  import 'errore';
5
5
  import 'ai';
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MethodName, S as StorageMethods } from './client-9A8NO6x9.js';
2
- export { A as AgentOptions, B as BuiltInToolName, E as ExecResult, G as GenerationOptions, I as InferUIMessage, L as ListResult, a as Message, b as MessageNotFoundError, c as MessageUsage, O as OnRestart, P as Part, R as ResolvedStorage, d as RpcPayload, e as RpcResult, f as Sandbox, g as SandboxConfig, h as SandboxError, i as SandboxNotFoundError, j as SandboxRecord, k as SandboxSetup, l as SendInput, m as Session, n as SessionNotFoundError, o as SessionOptions, p as SkillSummary, q as StepUsage, r as StorageConfig, s as StorageError, T as TagsSchema, t as ToolContext, U as UploadableFile, u as UsageSummary, v as agent, w as builtinToolNames } from './client-9A8NO6x9.js';
1
+ import { M as MethodName, S as StorageMethods } from './client-CKLwB-ES.js';
2
+ export { A as AgentDataTypes, a as AgentOptions, b as AgentStatus, c as AgentStream, B as BuiltInToolName, E as ExecResult, G as GenerationOptions, I as InferUIMessage, L as ListResult, d as Message, e as MessageNotFoundError, f as MessageUsage, O as OnRestart, P as Part, R as ResolvedStorage, g as RpcPayload, h as RpcResult, i as Sandbox, j as SandboxConfig, k as SandboxError, l as SandboxNotFoundError, m as SandboxRecord, n as SandboxSetup, o as SendInput, p as Session, q as SessionNotFoundError, r as SessionOptions, s as SkillSummary, t as StepUsage, u as StorageConfig, v as StorageError, T as TagsSchema, w as ToolContext, U as UploadableFile, x as UsageSummary, y as agent, z as builtinToolNames } from './client-CKLwB-ES.js';
3
3
  import { z } from 'zod';
4
4
  import 'errore';
5
5
  import 'ai';