@salesforce/sfdx-agent-sdk 0.21.0 → 0.22.0

package/dist/types/wire-communication-event.d.ts

@@ -0,0 +1,124 @@
+import type { UsageMetadata } from './usage.js';
+/**
+ * Wire-level communication events, emitted by the harness layer so consumers
+ * see the same shape regardless of harness. The union has three members today:
+ *   - `LlmRequestEvent` (`type: 'llm-request'`) — one outbound HTTP request to
+ *     the LLM provider.
+ *   - `LlmResponseEvent` (`type: 'llm-response'`) — the matching inbound
+ *     response (or terminal failure).
+ *   - `WireMonitoringNotSupportedEvent` (`type: 'wire-monitoring-not-supported'`)
+ *     — emitted by harnesses whose runtime doesn't expose a programmatic seam
+ *     for per-call wire monitoring (e.g. the Claude harness, where the
+ *     subprocess owns the HTTP traffic). The event carries a free-form
+ *     `message` explaining the situation and (when applicable) where the
+ *     underlying data was written instead.
+ *
+ * **Privacy contract.** Wire-communication events may contain user prompts,
+ * tool arguments, model output, and other PII. They are opt-in (subscribed
+ * to via `AgentManager.onWireCommunication`), not flowed to log files by
+ * default, and intended for diagnostic / debugging use rather than
+ * production observability. Consumers must apply their own redaction before
+ * persisting these events.
+ *
+ * **OTel disambiguation.** Despite the related-sounding name, this is NOT a
+ * distributed trace (a tree of spans across services produced by
+ * OpenTelemetry / Jaeger / Zipkin / Honeycomb). The `xClientTraceId`
+ * correlation header is a label for matching gateway-side logs, not a span.
+ *
+ * **Cross-harness fidelity.** Differs by harness:
+ *   - Mastra (in-process) emits one `LlmRequestEvent` + `LlmResponseEvent`
+ *     pair per outbound HTTP call, with the full request body captured.
+ *   - The Claude harness can't observe per-call HTTP traffic — the Claude
+ *     Agent SDK runs the model client in a subprocess with no programmatic
+ *     interception seam. Instead, when subscribers exist at stream-start, the
+ *     Claude harness writes the subprocess's debug log to a file under the
+ *     SDK storage root and emits a single `WireMonitoringNotSupportedEvent`
+ *     per stream, with the file path embedded in `message`.
+ *
+ * **Subscriber-presence gating.** The wire-communication event chain
+ * (`harness.wireBus → router slice → manager.wireBus`) uses
+ * `EventBus.forwardWhileSubscribed`, so a harness with zero downstream
+ * consumers pays zero cost — the Claude harness in particular skips writing
+ * the debug log and skips emitting the `WireMonitoringNotSupportedEvent`
+ * when nobody's listening. Consumers must subscribe via
+ * `AgentManager.onWireCommunication` BEFORE the `chat()` they want to
+ * observe; subscribing mid-stream misses the in-flight subprocess on Claude.
+ */
+export type LlmRequestEvent = {
+    /** Direction discriminator. */
+    type: 'llm-request';
+    /** Wall-clock timestamp when the request was emitted. */
+    timestamp: Date;
+    /** Fully-qualified URL the harness made the request to. */
+    url: string;
+    /** HTTP method (`POST`, `GET`, …). */
+    method: string;
+    /** Native model id sent on the wire (per `ModelConnectivityInfo.nativeModelId`). */
+    model: string;
+    /** Request body. Best-effort: partial / absent on harnesses that can't observe it. */
+    body?: Record<string, unknown>;
+};
+export type LlmResponseEvent = {
+    /** Direction discriminator. */
+    type: 'llm-response';
+    /** Wall-clock timestamp when the response (or terminal failure) was emitted. */
+    timestamp: Date;
+    /** Native model id from the matching request. */
+    model: string;
+    /** HTTP status code; `0` for harness-internal terminal failures with no transport response. */
+    status: number;
+    /** Error captured from a transport / parse failure, if any. */
+    error?: Error;
+    /**
+     * Time from request emit to first byte of response body, in ms.
+     *
+     * Best-effort and harness-dependent: only populated by harnesses that observe
+     * chunk timing on the streaming body. Today the Mastra fetch wrapper emits the
+     * `response` event when `globalThis.fetch` resolves (before any chunk has been
+     * consumed), so this field is typically `undefined` on Mastra. Consumers should
+     * treat the field as advisory and tolerate `undefined`.
+     */
+    timeToFirstTokenMs?: number;
+    /** Per-call token usage, if reported by the upstream. */
+    usage?: UsageMetadata;
+    /** Wall-clock duration from request emit to terminal event. */
+    totalDurationMs?: number;
+    /** Best-effort extracted response text (may be omitted by the harness). */
+    responseText?: string;
+    /** `x-client-trace-id` header value the SDK / harness attached to the request. */
+    xClientTraceId?: string;
+};
+/**
+ * Emitted by harnesses whose runtime doesn't expose a programmatic seam for
+ * per-call wire monitoring. The event signals to consumers that
+ * `LlmRequestEvent` / `LlmResponseEvent` won't be produced for this stream
+ * and, in `message`, points at whatever workaround the harness can offer
+ * (typically a debug log file path).
+ *
+ * The Claude harness emits this once per `stream()` call when subscribers
+ * exist at stream-start. The Mastra harness never emits it; it has the
+ * fetch-wrapper seam and produces structured request/response events
+ * directly.
+ */
+export type WireMonitoringNotSupportedEvent = {
+    /** Direction discriminator. */
+    type: 'wire-monitoring-not-supported';
+    /** Wall-clock timestamp when the event was emitted (typically end-of-stream). */
+    timestamp: Date;
+    /** Identifier of the harness emitting the event (e.g. `'claude'`). */
+    harnessId: string;
+    /**
+     * Free-form, human-readable explanation of why direct wire monitoring
+     * isn't available for this stream and where (if anywhere) the underlying
+     * data has been written instead. Treat as display text, not parseable
+     * structured data — harnesses may include file paths, URLs, or caveats
+     * inline. May contain newlines.
+     */
+    message: string;
+};
+/**
+ * Union over every wire-communication event the harness layer can emit.
+ * Discriminate on the `type` field.
+ */
+export type WireCommunicationEvent = LlmRequestEvent | LlmResponseEvent | WireMonitoringNotSupportedEvent;
+export type WireCommunicationEventCallback = (event: WireCommunicationEvent) => void;

package/dist/types/wire-communication-event.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export {};
+//# sourceMappingURL=wire-communication-event.js.map

package/dist/wire-communication-file-writer.d.ts

@@ -0,0 +1,39 @@
+import type { Unsubscribe } from '@salesforce/agentic-common';
+import type { WireCommunicationEvent } from './types/wire-communication-event.js';
+/**
+ * Source the writer subscribes to. Anything exposing `onWireCommunication(callback)`
+ * works — typically an {@link AgentManager}, but tests may construct a smaller
+ * surface.
+ */
+export type WireCommunicationEmitter = {
+    onWireCommunication(callback: (event: WireCommunicationEvent) => void): Unsubscribe;
+};
+export type WireCommunicationFileWriterOptions = {
+    /** Absolute (or cwd-relative) path the writer appends Markdown to. */
+    filePath: string;
+    /**
+     * Optional callback invoked when an `appendFile` rejection is observed
+     * (disk full, parent directory unwritable, etc.). Without this, write
+     * failures are routed to `console.error` so a debugging session can't
+     * silently lose events — the writer is itself a debugging aid, so a
+     * silently-empty file would be the worst possible failure mode.
+     */
+    onError?: (error: Error, event: WireCommunicationEvent) => void;
+};
+/**
+ * Subscribes to a {@link WireCommunicationEmitter} (typically an
+ * `AgentManager`) and writes each {@link WireCommunicationEvent} to a
+ * Markdown file. Used as a debugging aid — consumers can attach one with a
+ * single line and inspect the resulting file to see request / response pairs
+ * in chronological order.
+ *
+ * The output may contain user prompts, tool arguments, and model output —
+ * apply your own redaction before sharing the file.
+ */
+export declare class WireCommunicationFileWriter {
+    private options;
+    private unsubscribe;
+    constructor(emitter: WireCommunicationEmitter, options?: Partial<WireCommunicationFileWriterOptions>);
+    detach(): void;
+    private handleEvent;
+}

package/dist/wire-communication-file-writer.js

@@ -0,0 +1,142 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { appendFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+const DefaultWireCommunicationFileWriterOptions = {
+    filePath: resolve(process.cwd(), 'wire-communication.md'),
+};
+function validateOptions(options) {
+    if (typeof options.filePath !== 'string' || options.filePath.trim() === '') {
+        throw new Error('WireCommunicationFileWriterOptions.filePath must be a non-empty string');
+    }
+    return options;
+}
+/**
+ * Subscribes to a {@link WireCommunicationEmitter} (typically an
+ * `AgentManager`) and writes each {@link WireCommunicationEvent} to a
+ * Markdown file. Used as a debugging aid — consumers can attach one with a
+ * single line and inspect the resulting file to see request / response pairs
+ * in chronological order.
+ *
+ * The output may contain user prompts, tool arguments, and model output —
+ * apply your own redaction before sharing the file.
+ */
+export class WireCommunicationFileWriter {
+    options;
+    unsubscribe;
+    constructor(emitter, options = {}) {
+        const resolvedOptions = {
+            ...DefaultWireCommunicationFileWriterOptions,
+            ...options,
+        };
+        this.options = validateOptions(resolvedOptions);
+        this.unsubscribe = emitter.onWireCommunication((event) => {
+            void this.handleEvent(event);
+        });
+    }
+    detach() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+    }
+    async handleEvent(event) {
+        const content = formatAsMarkdown(event);
+        try {
+            await appendFile(this.options.filePath, content);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (this.options.onError) {
+                try {
+                    this.options.onError(error, event);
+                }
+                catch {
+                    // Swallow errors from a misbehaving consumer callback;
+                    // the writer must not throw out of the event listener.
+                }
+            }
+            else {
+                console.error(`[WireCommunicationFileWriter] Failed to append to "${this.options.filePath}":`, error);
+            }
+        }
+    }
+}
+function formatAsMarkdown(event) {
+    switch (event.type) {
+        case 'llm-request':
+            return formatRequestMarkdown(event);
+        case 'llm-response':
+            return formatResponseMarkdown(event);
+        case 'wire-monitoring-not-supported':
+            return formatWireMonitoringNotSupportedMarkdown(event);
+    }
+}
+function formatRequestMarkdown(event) {
+    const dateTime = event.timestamp.toISOString();
+    const body = event.body;
+    const lines = [
+        `### ${dateTime} [${event.type}]`,
+        ``,
+        `**Url**: ${event.method} ${event.url}`,
+        ``,
+        `**Model**: ${event.model}`,
+        ``,
+    ];
+    if (body !== undefined) {
+        lines.push(`**Body**:`, '```json', JSON.stringify(body, null, 2), '```', ``);
+    }
+    lines.push(``);
+    return lines.join('\n');
+}
+function formatResponseMarkdown(event) {
+    // Optional fields are emitted only when populated. Mastra's fetch wrapper
+    // populates `status`, `totalDurationMs`, and (when the gateway returns it)
+    // `xClientTraceId`; future harnesses may populate `usage`, `responseText`,
+    // and `timeToFirstTokenMs`. Skipping the unset fields keeps the markdown
+    // signal-dense rather than padding every section with `N/A` lines.
+    const dateTime = event.timestamp.toISOString();
+    const lines = [
+        `### ${dateTime} [${event.type}]`,
+        ``,
+        `**Model**: ${event.model}`,
+        ``,
+        `**Status**: ${event.status}`,
+        ``,
+    ];
+    if (event.xClientTraceId !== undefined) {
+        lines.push(`**x-client-trace-id**: ${event.xClientTraceId}`, ``);
+    }
+    if (event.totalDurationMs !== undefined) {
+        lines.push(`**Total duration**: ${event.totalDurationMs}`, ``);
+    }
+    if (event.timeToFirstTokenMs !== undefined) {
+        lines.push(`**Time to first token**: ${event.timeToFirstTokenMs}`, ``);
+    }
+    if (event.error !== undefined) {
+        lines.push(`**Error**: ${event.error.message}`, ``);
+    }
+    if (event.usage !== undefined) {
+        if (event.usage.inputTokens !== undefined) {
+            lines.push(`**Input tokens**: ${event.usage.inputTokens}`, ``);
+        }
+        if (event.usage.outputTokens !== undefined) {
+            lines.push(`**Output tokens**: ${event.usage.outputTokens}`, ``);
+        }
+        if (event.usage.totalTokens !== undefined) {
+            lines.push(`**Total tokens**: ${event.usage.totalTokens}`, ``);
+        }
+        if (event.usage.reasoningTokens !== undefined) {
+            lines.push(`**Reasoning tokens**: ${event.usage.reasoningTokens}`, ``);
+        }
+    }
+    if (event.responseText !== undefined) {
+        lines.push(`**Response**:`, event.responseText, ``);
+    }
+    return lines.join('\n');
+}
+function formatWireMonitoringNotSupportedMarkdown(event) {
+    const dateTime = event.timestamp.toISOString();
+    return [`### ${dateTime} [${event.type}]`, ``, `**Harness**: ${event.harnessId}`, ``, event.message, ``, ``].join('\n');
+}
+//# sourceMappingURL=wire-communication-file-writer.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -40,17 +40,16 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.10.0",
-    "@salesforce/llm-gateway-sdk": "0.14.0"
+    "@salesforce/agentic-common": "0.11.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.17.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.20.0",
-    "@types/node": "^22.19.20",
+    "@salesforce/sfdx-agent-harness-claude": "0.18.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.21.0",
+    "@types/node": "^22.19.21",
     "@vitest/coverage-istanbul": "^4.1.8",
-    "@vitest/eslint-plugin": "^1.6.19",
-    "eslint": "^10.4.1",
+    "@vitest/eslint-plugin": "^1.6.20",
+    "eslint": "^10.5.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",