@meistrari/agent-sdk 0.1.0 → 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 (7) hide show
  1. package/README.md +67 -16
  2. package/dist/index.cjs +16 -1
  3. package/dist/index.d.cts +18 -0
  4. package/dist/index.d.mts +18 -0
  5. package/dist/index.d.ts +18 -0
  6. package/dist/index.mjs +16 -1
  7. package/package.json +41 -41
package/README.md CHANGED
@@ -12,6 +12,8 @@ bun add @meistrari/agent-sdk
12
12
 
13
13
  ## Usage
14
14
 
15
+ ### Start and stream a session
16
+
15
17
  ```ts
16
18
  import { agentClient, DataTokenAuthStrategy } from '@meistrari/agent-sdk'
17
19
 
@@ -21,7 +23,6 @@ const client = agentClient({
21
23
  vaultUrl: 'https://vault.example.com', // required only for resolveReference
22
24
  })
23
25
 
24
- // 1) Execute an agent
25
26
  const { success, sessionId, error } = await client.executeAgent({
26
27
  organizationName: 'acme',
27
28
  repository: 'support-bot',
@@ -29,24 +30,74 @@ const { success, sessionId, error } = await client.executeAgent({
29
30
  inputs: [{ vaultRef: 'vault://...', filename: 'tickets.csv' }],
30
31
  })
31
32
 
32
- // 2) Consume the session as a typed async-iterable.
33
- // The server already inlines step/result Vault bytes into the stream.
34
- if (success && sessionId) {
35
- for await (const event of client.streamSession(sessionId, { signal })) {
36
- switch (event.kind) {
37
- case 'status': // pending | running | completed | failed | waiting_messages | cancelled
38
- break
39
- case 'steps': // live step tail
40
- break
41
- case 'result': // final accumulated result
42
- break
43
- case 'error':
44
- throw new Error(event.error)
45
- }
33
+ if (!success || !sessionId)
34
+ throw new Error(error ?? 'Agent execution was not accepted')
35
+
36
+ let cursor: number | undefined
37
+ let readyForFollowUp = false
38
+
39
+ // The server already inlines step/result Vault bytes into the stream.
40
+ for await (const event of await client.streamSession(sessionId, { signal })) {
41
+ if ('nextCursor' in event && event.nextCursor !== null)
42
+ cursor = event.nextCursor
43
+
44
+ switch (event.kind) {
45
+ case 'status': // pending | running | completed | failed | waiting_messages | cancelled
46
+ break
47
+ case 'steps': // live step tail
48
+ break
49
+ case 'result': // final accumulated result
50
+ readyForFollowUp = event.status === 'waiting_messages'
51
+ break
52
+ case 'error':
53
+ throw new Error(event.error)
46
54
  }
47
55
  }
56
+ ```
57
+
58
+ ### Continue a multi-turn session
59
+
60
+ For v4 sandbox sessions, `executeAgent` is both the start and continue method. Call it
61
+ with `organizationName`, `repository`, and `message` to start a session. Call it with
62
+ `sessionId` and a new `message` to continue an existing multi-turn session.
63
+
64
+ ```ts
65
+ if (!readyForFollowUp)
66
+ throw new Error('Session is not waiting for follow-up messages')
67
+
68
+ const followUp = await client.executeAgent({
69
+ sessionId,
70
+ message: 'Which tickets should we prioritize first?',
71
+ inputs: [{ vaultRef: 'vault://...', filename: 'sla-rules.md' }],
72
+ environmentVariables: { SUPPORT_REGION: 'us' },
73
+ })
74
+
75
+ if (!followUp.success)
76
+ throw new Error(followUp.error ?? 'Agent continuation was not accepted')
77
+
78
+ for await (const event of await client.streamSession(sessionId, { cursor, signal })) {
79
+ if ('nextCursor' in event && event.nextCursor !== null)
80
+ cursor = event.nextCursor
81
+
82
+ // Handle only events newer than the cursor from the previous turn.
83
+ }
84
+ ```
85
+
86
+ Multi-turn lifecycle rules:
87
+
88
+ - New sessions require `organizationName`, `repository`, and `message`.
89
+ - Continuations require `sessionId` and `message`; `inputs` and `environmentVariables` are optional per turn.
90
+ - Recovery requests require `sessionId` and `recover: true`; `message` is not required.
91
+ - Continue only after the stream reaches a `result` event with `status: 'waiting_messages'`.
92
+ - Continuations while the session is `pending` or `running` fail with `409`.
93
+ - Treat `completed`, `failed`, and `cancelled` as non-normal follow-up states in SDK consumers.
94
+ - The SDK v4 path does not use the legacy `/v3/sessions/{sessionId}/continue` endpoint.
95
+
96
+ ### Resolve Vault references
97
+
98
+ ```ts
48
99
 
49
- // 3) Resolve a vault:// reference (e.g. an output file ref found in a result)
100
+ // Resolve a vault:// reference, e.g. an output file ref found in a result.
50
101
  const bytes = await client.resolveReference('vault://...')
51
102
  const stream = await client.resolveReference('vault://...', { as: 'stream' })
52
103
  const json = await client.resolveReference<MyShape>('vault://...', { as: 'json' })
package/dist/index.cjs CHANGED
@@ -89,6 +89,8 @@ const executeAgentRequestSchema = zod.z.object({
89
89
  if (!data.message) {
90
90
  ctx.addIssue({ code: "custom", message: "message is required for new sessions", path: ["message"] });
91
91
  }
92
+ } else if (!data.recover && !data.message) {
93
+ ctx.addIssue({ code: "custom", message: "message is required for session continuations", path: ["message"] });
92
94
  }
93
95
  if (data.recover && !data.sessionId) {
94
96
  ctx.addIssue({ code: "custom", message: "sessionId is required when recover is true", path: ["sessionId"] });
@@ -130,13 +132,26 @@ const sessionErrorEventSchema = zod.z.object({
130
132
  sessionId: zod.z.string(),
131
133
  error: zod.z.string()
132
134
  });
135
+ const sessionTimelineFinalizeEventSchema = zod.z.object({
136
+ kind: zod.z.literal("timeline-finalize"),
137
+ sessionId: zod.z.string(),
138
+ status: sessionStatusSchema,
139
+ metrics: zod.z.record(zod.z.string(), zod.z.unknown()).nullable().optional(),
140
+ prompt: zod.z.record(zod.z.string(), zod.z.unknown()).nullable().optional(),
141
+ spans: zod.z.array(zod.z.record(zod.z.string(), zod.z.unknown())).nullable().optional(),
142
+ events: zod.z.array(zod.z.record(zod.z.string(), zod.z.unknown())).nullable().optional(),
143
+ continuation: zod.z.record(zod.z.string(), zod.z.unknown()).nullable().optional(),
144
+ createdAt: zod.z.number(),
145
+ updatedAt: zod.z.number()
146
+ });
133
147
  const sessionStreamEventSchema = zod.z.discriminatedUnion("kind", [
134
148
  sessionStatusEventSchema,
135
149
  sessionStepsEventSchema,
136
150
  sessionResultEventSchema,
151
+ sessionTimelineFinalizeEventSchema,
137
152
  sessionErrorEventSchema
138
153
  ]);
139
- const SESSION_STREAM_EVENT_KINDS = /* @__PURE__ */ new Set(["status", "steps", "result", "error"]);
154
+ const SESSION_STREAM_EVENT_KINDS = /* @__PURE__ */ new Set(["status", "steps", "result", "timeline-finalize", "error"]);
140
155
 
141
156
  function normalizeStreamBuffer(buffer) {
142
157
  return buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
package/dist/index.d.cts CHANGED
@@ -90,6 +90,24 @@ declare const sessionStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
90
90
  nextCursor: z.ZodNullable<z.ZodNumber>;
91
91
  createdAt: z.ZodNumber;
92
92
  updatedAt: z.ZodNumber;
93
+ }, z.core.$strip>, z.ZodObject<{
94
+ kind: z.ZodLiteral<"timeline-finalize">;
95
+ sessionId: z.ZodString;
96
+ status: z.ZodEnum<{
97
+ pending: "pending";
98
+ running: "running";
99
+ completed: "completed";
100
+ failed: "failed";
101
+ waiting_messages: "waiting_messages";
102
+ cancelled: "cancelled";
103
+ }>;
104
+ metrics: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
105
+ prompt: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
106
+ spans: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
107
+ events: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
108
+ continuation: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
109
+ createdAt: z.ZodNumber;
110
+ updatedAt: z.ZodNumber;
93
111
  }, z.core.$strip>, z.ZodObject<{
94
112
  kind: z.ZodLiteral<"error">;
95
113
  sessionId: z.ZodString;
package/dist/index.d.mts CHANGED
@@ -90,6 +90,24 @@ declare const sessionStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
90
90
  nextCursor: z.ZodNullable<z.ZodNumber>;
91
91
  createdAt: z.ZodNumber;
92
92
  updatedAt: z.ZodNumber;
93
+ }, z.core.$strip>, z.ZodObject<{
94
+ kind: z.ZodLiteral<"timeline-finalize">;
95
+ sessionId: z.ZodString;
96
+ status: z.ZodEnum<{
97
+ pending: "pending";
98
+ running: "running";
99
+ completed: "completed";
100
+ failed: "failed";
101
+ waiting_messages: "waiting_messages";
102
+ cancelled: "cancelled";
103
+ }>;
104
+ metrics: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
105
+ prompt: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
106
+ spans: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
107
+ events: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
108
+ continuation: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
109
+ createdAt: z.ZodNumber;
110
+ updatedAt: z.ZodNumber;
93
111
  }, z.core.$strip>, z.ZodObject<{
94
112
  kind: z.ZodLiteral<"error">;
95
113
  sessionId: z.ZodString;
package/dist/index.d.ts CHANGED
@@ -90,6 +90,24 @@ declare const sessionStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
90
90
  nextCursor: z.ZodNullable<z.ZodNumber>;
91
91
  createdAt: z.ZodNumber;
92
92
  updatedAt: z.ZodNumber;
93
+ }, z.core.$strip>, z.ZodObject<{
94
+ kind: z.ZodLiteral<"timeline-finalize">;
95
+ sessionId: z.ZodString;
96
+ status: z.ZodEnum<{
97
+ pending: "pending";
98
+ running: "running";
99
+ completed: "completed";
100
+ failed: "failed";
101
+ waiting_messages: "waiting_messages";
102
+ cancelled: "cancelled";
103
+ }>;
104
+ metrics: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
105
+ prompt: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
106
+ spans: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
107
+ events: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
108
+ continuation: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
109
+ createdAt: z.ZodNumber;
110
+ updatedAt: z.ZodNumber;
93
111
  }, z.core.$strip>, z.ZodObject<{
94
112
  kind: z.ZodLiteral<"error">;
95
113
  sessionId: z.ZodString;
package/dist/index.mjs CHANGED
@@ -87,6 +87,8 @@ const executeAgentRequestSchema = z.object({
87
87
  if (!data.message) {
88
88
  ctx.addIssue({ code: "custom", message: "message is required for new sessions", path: ["message"] });
89
89
  }
90
+ } else if (!data.recover && !data.message) {
91
+ ctx.addIssue({ code: "custom", message: "message is required for session continuations", path: ["message"] });
90
92
  }
91
93
  if (data.recover && !data.sessionId) {
92
94
  ctx.addIssue({ code: "custom", message: "sessionId is required when recover is true", path: ["sessionId"] });
@@ -128,13 +130,26 @@ const sessionErrorEventSchema = z.object({
128
130
  sessionId: z.string(),
129
131
  error: z.string()
130
132
  });
133
+ const sessionTimelineFinalizeEventSchema = z.object({
134
+ kind: z.literal("timeline-finalize"),
135
+ sessionId: z.string(),
136
+ status: sessionStatusSchema,
137
+ metrics: z.record(z.string(), z.unknown()).nullable().optional(),
138
+ prompt: z.record(z.string(), z.unknown()).nullable().optional(),
139
+ spans: z.array(z.record(z.string(), z.unknown())).nullable().optional(),
140
+ events: z.array(z.record(z.string(), z.unknown())).nullable().optional(),
141
+ continuation: z.record(z.string(), z.unknown()).nullable().optional(),
142
+ createdAt: z.number(),
143
+ updatedAt: z.number()
144
+ });
131
145
  const sessionStreamEventSchema = z.discriminatedUnion("kind", [
132
146
  sessionStatusEventSchema,
133
147
  sessionStepsEventSchema,
134
148
  sessionResultEventSchema,
149
+ sessionTimelineFinalizeEventSchema,
135
150
  sessionErrorEventSchema
136
151
  ]);
137
- const SESSION_STREAM_EVENT_KINDS = /* @__PURE__ */ new Set(["status", "steps", "result", "error"]);
152
+ const SESSION_STREAM_EVENT_KINDS = /* @__PURE__ */ new Set(["status", "steps", "result", "timeline-finalize", "error"]);
138
153
 
139
154
  function normalizeStreamBuffer(buffer) {
140
155
  return buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
package/package.json CHANGED
@@ -1,44 +1,44 @@
1
1
  {
2
- "name": "@meistrari/agent-sdk",
3
- "type": "module",
4
- "version": "0.1.0",
5
- "license": "UNLICENSED",
6
- "repository": {
7
- "type": "git",
8
- "url": "https://github.com/meistrari/agent-api.git",
9
- "directory": "packages/agent-sdk"
10
- },
11
- "exports": {
12
- ".": {
13
- "bun": "./src/index.ts",
14
- "types": "./dist/index.d.ts",
15
- "import": "./dist/index.mjs",
16
- "require": "./dist/index.cjs"
17
- }
18
- },
19
- "main": "dist/index.mjs",
20
- "types": "dist/index.d.ts",
21
- "files": [
22
- "dist"
23
- ],
24
- "scripts": {
25
- "build": "unbuild",
26
- "typecheck": "bunx tsc --noEmit",
27
- "test:unit": "bun test test/",
28
- "lint": "eslint ."
29
- },
30
- "peerDependencies": {
31
- "typescript": "^5.0.0"
32
- },
33
- "dependencies": {
34
- "@meistrari/vault-sdk": "1.9.0",
35
- "zod": "4.1.12"
36
- },
37
- "devDependencies": {
38
- "@types/bun": "latest",
39
- "unbuild": "2.0.0"
40
- },
41
- "publishConfig": {
42
- "access": "public"
2
+ "name": "@meistrari/agent-sdk",
3
+ "type": "module",
4
+ "version": "0.1.2",
5
+ "license": "UNLICENSED",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/meistrari/agent-api.git",
9
+ "directory": "packages/agent-sdk"
10
+ },
11
+ "exports": {
12
+ ".": {
13
+ "bun": "./src/index.ts",
14
+ "types": "./dist/index.d.ts",
15
+ "import": "./dist/index.mjs",
16
+ "require": "./dist/index.cjs"
43
17
  }
18
+ },
19
+ "main": "dist/index.mjs",
20
+ "types": "dist/index.d.ts",
21
+ "files": [
22
+ "dist"
23
+ ],
24
+ "scripts": {
25
+ "build": "unbuild",
26
+ "typecheck": "bunx tsc --noEmit",
27
+ "test:unit": "bun test test/",
28
+ "lint": "eslint ."
29
+ },
30
+ "peerDependencies": {
31
+ "typescript": "^5.0.0"
32
+ },
33
+ "dependencies": {
34
+ "@meistrari/vault-sdk": "1.9.0",
35
+ "zod": "4.1.12"
36
+ },
37
+ "devDependencies": {
38
+ "@types/bun": "latest",
39
+ "unbuild": "2.0.0"
40
+ },
41
+ "publishConfig": {
42
+ "access": "public"
43
+ }
44
44
  }