xmemory 3.5.0 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -184,8 +184,13 @@ Extract and store structured objects from text:
184
184
  const result = await inst.write("Bob is a designer based in Berlin.");
185
185
  console.log(result.write_id, result.trace_id);
186
186
  console.log(result.changes); // what the write created / updated / deleted
187
+ console.log(result.console_url); // this operation's trace in the console, or null
187
188
  ```
188
189
 
190
+ Every data operation — `read`, `write`, `writeAsync`, `writeStatus`, `extract` — carries
191
+ `console_url`, the deep link to that call's trace. It is per operation rather than per
192
+ record, and `null` when the server has no console configured.
193
+
189
194
  Options: `{ extractionLogic?, diffEngine?, timeoutMs? }` — `extractionLogic` defaults to `"fast"`.
190
195
 
191
196
  Or pass a `WriteMutation[]` for **structured writes** — deterministic, LLM-free
@@ -304,7 +309,7 @@ console.log(schema.data_schema);
304
309
 
305
310
  ### `inst.describe(options?)` → `DescribeResult`
306
311
 
307
- Get agent-facing tool descriptions enriched with the instance's schema.
312
+ Get the agent-facing tool descriptions for an instance, with its schema in `schemaSummary`.
308
313
 
309
314
  ```typescript
310
315
  const desc = await inst.describe();
@@ -108,7 +108,9 @@ export declare class InstanceHandle {
108
108
  */
109
109
  applyPendingDecisions(proposalVersion: string, options?: SuggestionRequestOptions): Promise<ApplyPendingDecisionsResult>;
110
110
  /**
111
- * Return agent-facing tool descriptions enriched with the instance schema.
111
+ * Return the agent-facing tool descriptions for this instance.
112
+ *
113
+ * The instance's schema comes back in `DescribeResult.schemaSummary`.
112
114
  *
113
115
  * Results are cached locally with a TTL (default 5 min).
114
116
  * Call `clearDescribeCache()` to force a refresh.
package/dist/instance.js CHANGED
@@ -168,6 +168,17 @@ function buildJsonSchemaProps(params) {
168
168
  }
169
169
  return { properties, required };
170
170
  }
171
+ /**
172
+ * Normalize a missing `console_url` to `null`.
173
+ *
174
+ * The server omits the field rather than sending null when no console is configured,
175
+ * so without this a caller comparing against `null` would be reading `undefined` on
176
+ * exactly the deployments that have no link — the case the comparison exists for.
177
+ * Same treatment `read` already gives `reader_results`.
178
+ */
179
+ function withConsoleUrl(result) {
180
+ return { ...result, console_url: result.console_url ?? null };
181
+ }
171
182
  export class InstanceHandle {
172
183
  id;
173
184
  _requestOne;
@@ -203,35 +214,29 @@ export class InstanceHandle {
203
214
  body,
204
215
  timeoutMs: options?.timeoutMs,
205
216
  });
206
- return { ...result, reader_results: result.reader_results ?? [] };
217
+ return withConsoleUrl({ ...result, reader_results: result.reader_results ?? [] });
207
218
  }
208
219
  async write(input, options) {
209
- return this._requestOne("POST", `/instances/${this.id}/write`, {
210
- body: buildWriteBody(input, options),
211
- timeoutMs: options?.timeoutMs,
212
- });
220
+ return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write`, { body: buildWriteBody(input, options), timeoutMs: options?.timeoutMs }));
213
221
  }
214
222
  async writeAsync(input, options) {
215
- return this._requestOne("POST", `/instances/${this.id}/write_async`, {
223
+ const result = await this._requestOne("POST", `/instances/${this.id}/write_async`, {
216
224
  body: buildWriteBody(input, options),
217
225
  timeoutMs: options?.timeoutMs,
218
226
  });
227
+ // `trace_id` is normalized here as well because this result declares it for the
228
+ // first time, and the wire omits it exactly as it omits the console link.
229
+ return withConsoleUrl({ ...result, trace_id: result.trace_id ?? null });
219
230
  }
220
231
  async writeStatus(writeId, options) {
221
- return this._requestOne("POST", `/instances/${this.id}/write_status`, {
222
- body: { write_id: writeId },
223
- timeoutMs: options?.timeoutMs,
224
- });
232
+ return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
225
233
  }
226
234
  async extract(text, options) {
227
235
  const body = {
228
236
  text,
229
237
  extraction_logic: options?.extractionLogic ?? "fast",
230
238
  };
231
- return this._requestOne("POST", `/instances/${this.id}/extract`, {
232
- body,
233
- timeoutMs: options?.timeoutMs,
234
- });
239
+ return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/extract`, { body, timeoutMs: options?.timeoutMs }));
235
240
  }
236
241
  async getSchema(options) {
237
242
  return this._requestOne("GET", `/instances/${this.id}/schema`, {
@@ -290,7 +295,9 @@ export class InstanceHandle {
290
295
  });
291
296
  }
292
297
  /**
293
- * Return agent-facing tool descriptions enriched with the instance schema.
298
+ * Return the agent-facing tool descriptions for this instance.
299
+ *
300
+ * The instance's schema comes back in `DescribeResult.schemaSummary`.
294
301
  *
295
302
  * Results are cached locally with a TTL (default 5 min).
296
303
  * Call `clearDescribeCache()` to force a refresh.
package/dist/types.d.ts CHANGED
@@ -155,6 +155,8 @@ export interface TaggedReaderResult {
155
155
  }
156
156
  export interface ReadResult {
157
157
  readonly trace_id: string | null;
158
+ /** Deep link to this read's trace in the console; `null` if no console is configured. */
159
+ readonly console_url: string | null;
158
160
  readonly reader_result: unknown;
159
161
  /**
160
162
  * Per-sub-query answers when the server decomposed the query into independent
@@ -169,20 +171,30 @@ export interface ReadResult {
169
171
  export interface WriteResult {
170
172
  readonly write_id: string;
171
173
  readonly trace_id: string | null;
174
+ /** Deep link to this write's trace in the console; `null` if no console is configured. */
175
+ readonly console_url: string | null;
172
176
  /** What the write did, grouped into `created` / `updated` / `deleted`. */
173
177
  readonly changes: unknown;
174
178
  }
175
179
  export interface AsyncWriteResult {
176
180
  readonly write_id: string;
181
+ /** Trace id for the queued write, echoed by the server; `null` if it sent none. */
182
+ readonly trace_id: string | null;
183
+ /** Deep link to this write's trace in the console; `null` if no console is configured. */
184
+ readonly console_url: string | null;
177
185
  }
178
186
  export interface WriteStatusResult {
179
187
  readonly write_id: string;
180
188
  readonly write_status: WriteQueueStatus;
189
+ /** Deep link to the underlying write's trace; `null` if no console is configured. */
190
+ readonly console_url: string | null;
181
191
  readonly error_detail: string | null;
182
192
  readonly completed_at: string | null;
183
193
  }
184
194
  export interface ExtractResult {
185
195
  readonly trace_id: string | null;
196
+ /** Deep link to this extraction's trace in the console; `null` if no console is configured. */
197
+ readonly console_url: string | null;
186
198
  readonly objects_extracted: unknown;
187
199
  }
188
200
  export interface GenerateSchemaResult {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.5.0",
3
+ "version": "3.6.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"