@agentic-kit/dsh 0.2.0

package/schema.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDshParameters = void 0;
+exports.convertDshParameters = convertDshParameters;
+const zod_1 = require("zod");
+/**
+ * A neutral tool's zod parameters, as dsh's JSON Schema subset.
+ *
+ * dsh enforces a deliberately small schema vocabulary on every registered tool:
+ * `type`, `properties`, `required`, `items`, `oneOf`, `enum`, `const`, a boolean
+ * `additionalProperties`, and the annotations. A zod schema routinely produces
+ * more than that — `format` from `.uuid()`, `minimum`, `minItems`, `anyOf` from
+ * a union, an object-valued `additionalProperties` from a record, `$defs`/`$ref`
+ * from a reused sub-schema — and dsh rejects a tool carrying any of them.
+ *
+ * So this narrows: unsupported *constraints* are dropped, and unsupported
+ * *structure* throws. Dropping a constraint is safe here and only here, because
+ * the schema dsh receives is a hint to the model, not the enforcement:
+ * `toDshTool` parses the model's arguments with the tool's own zod schema
+ * before the body runs, so every constraint this drops is still applied — by
+ * the party that owns it. What cannot degrade is the shape a caller has to
+ * satisfy, which is why a non-object root or an unresolvable `$ref` is an error
+ * rather than an open schema.
+ */
+const CONSTRAINTS = new Set([
+    'type',
+    'properties',
+    'required',
+    'items',
+    'oneOf',
+    'enum',
+    'const',
+    'additionalProperties'
+]);
+const ANNOTATIONS = new Set(['description', 'title', 'default', 'examples']);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function narrow(node, path, dropped) {
+    if (!isRecord(node))
+        return {};
+    if (typeof node.$ref === 'string') {
+        throw new Error(`tool parameters use a JSON Schema $ref ("${node.$ref}") at ${path || 'the root'}; ` +
+            'dsh reads no references, so the schema must be inlined');
+    }
+    const out = {};
+    const source = widenUnions(node, path, dropped);
+    for (const [key, value] of Object.entries(source)) {
+        const at = path === '' ? key : `${path}.${key}`;
+        if (key === '$schema' || key === '$defs' || key === 'definitions')
+            continue;
+        if (ANNOTATIONS.has(key)) {
+            out[key] = value;
+            continue;
+        }
+        if (!CONSTRAINTS.has(key)) {
+            dropped.push(at);
+            continue;
+        }
+        switch (key) {
+            case 'properties': {
+                const properties = {};
+                for (const [name, sub] of Object.entries(isRecord(value) ? value : {})) {
+                    properties[name] = narrow(sub, `${at}.${name}`, dropped);
+                }
+                out.properties = properties;
+                break;
+            }
+            case 'items':
+                out.items = narrow(value, at, dropped);
+                break;
+            case 'oneOf':
+                out.oneOf = (Array.isArray(value) ? value : []).map((sub, index) => narrow(sub, `${at}[${index}]`, dropped));
+                break;
+            case 'additionalProperties':
+                // Only the boolean form exists in dsh's subset; a zod record's
+                // object-valued form degrades to the open default.
+                if (typeof value === 'boolean')
+                    out.additionalProperties = value;
+                else
+                    dropped.push(at);
+                break;
+            default:
+                out[key] = value;
+        }
+    }
+    // `required` may not name a property the narrowed schema no longer declares.
+    if (Array.isArray(out.required)) {
+        const declared = new Set(Object.keys(out.properties ?? {}));
+        const kept = out.required.filter((name) => typeof name === 'string' && declared.has(name));
+        if (kept.length === 0)
+            delete out.required;
+        else
+            out.required = kept;
+    }
+    return out;
+}
+/**
+ * `anyOf` and a type array as dsh's `oneOf`, where that is sound.
+ *
+ * zod emits `anyOf` for a union and `type: ['string', 'null']` for a nullable;
+ * dsh has neither, only `oneOf` — which validates *exactly one* branch. That is
+ * the same thing as `anyOf` only when the branches are disjoint, which is true
+ * of the shapes zod actually produces here (a nullable, a union of distinct
+ * scalar types) and not true in general. So a disjoint union converts, and an
+ * overlapping one degrades to unconstrained rather than becoming a schema that
+ * rejects a legitimate argument.
+ */
+function widenUnions(node, path, dropped) {
+    const rest = { ...node };
+    let branches;
+    if (Array.isArray(rest.anyOf)) {
+        branches = rest.anyOf;
+        delete rest.anyOf;
+    }
+    else if (Array.isArray(rest.type)) {
+        branches = rest.type.map((type) => ({ type }));
+        delete rest.type;
+    }
+    if (!branches || rest.oneOf !== undefined)
+        return node;
+    const types = branches.map((branch) => isRecord(branch) && typeof branch.type === 'string' ? branch.type : undefined);
+    const disjoint = branches.length >= 2 &&
+        types.every((type) => type !== undefined) &&
+        new Set(types).size === types.length;
+    if (!disjoint) {
+        dropped.push(path === '' ? 'anyOf' : `${path}.anyOf`);
+        return rest;
+    }
+    return { ...rest, oneOf: branches };
+}
+/** Convert and report, for a host that wants to see what degraded. */
+function convertDshParameters(schema) {
+    const dropped = [];
+    // zod's own emitter, in input mode (what a *caller* must send) against
+    // draft-7 — the dialect dsh's subset is carved out of.
+    const jsonSchema = zod_1.z.toJSONSchema(schema, { target: 'draft-7', io: 'input' });
+    const narrowed = narrow(jsonSchema, '', dropped);
+    if (narrowed.type !== 'object') {
+        throw new Error(`tool parameters must be an object schema; received ${String(narrowed.type ?? 'no type')}. ` +
+            'dsh names every argument, so a tool cannot take a bare value or a top-level union');
+    }
+    return {
+        parameters: {
+            type: 'object',
+            properties: narrowed.properties ?? {},
+            ...(narrowed.required ? { required: narrowed.required } : {}),
+            ...(narrowed.description ? { description: narrowed.description } : {})
+        },
+        dropped
+    };
+}
+/** The dsh-subset JSON Schema for a tool's parameters. */
+const toDshParameters = (schema) => convertDshParameters(schema).parameters;
+exports.toDshParameters = toDshParameters;

package/transcript.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DeepSeek Harness's transcript reader: dsh session events → neutral events.
+ *
+ * The read half of the adapter, and deliberately the only file in this package
+ * a renderer imports (`@agentic-kit/dsh/transcript`): it is browser-safe, has
+ * no dsh dependency and no db-tools dependency, so a dashboard can project a
+ * dsh run without pulling a node graph. `@agentic-kit/run-log` owns the neutral
+ * vocabulary and the registry; the format's meaning lives here, beside the
+ * adapter that produces it.
+ *
+ * dsh's log differs from pi's in three ways that matter:
+ * - it is an *event* log, not a message log: a tool call and its result are
+ *   separate events with their own sequence numbers, and a step boundary is an
+ *   event of its own;
+ * - `time` is epoch milliseconds, not an ISO string;
+ * - assistant reasoning is a `reasoning` content block, and a tool call's
+ *   arguments arrive as the raw JSON string the model produced.
+ *
+ * Register the reader once at host startup, e.g.
+ * `transcriptReaders.register(dshTranscriptReader)`.
+ */
+import { type TranscriptEntry, type TranscriptEvent, type TranscriptReader } from '@agentic-kit/run-log';
+/** dsh's session-event log (`@deepseek-ai/dsh-session`). */
+export declare const DSH_TRANSCRIPT_FORMAT = "dsh";
+/**
+ * dsh's `SESSION_FORMAT_VERSION` as of `0.1.0-rc.7`. It bumps only when the
+ * event envelope or the surface mechanism changes — a new event *type* does
+ * not bump it, which is why an unrecognized type here becomes an `unknown`
+ * event rather than a refusal.
+ */
+export declare const SUPPORTED_DSH_TRANSCRIPT_VERSION = 0;
+/** One entry of a dsh session log, structurally. */
+export interface DshSessionEvent extends TranscriptEntry {
+    type: string;
+    seq?: number;
+    time?: number;
+    data?: Record<string, unknown>;
+}
+/**
+ * Narrow an untrusted dsh event. `seq` and `time` are part of dsh's envelope
+ * rather than optional decoration, so an entry missing them is not a dsh event
+ * and must not be stored as one.
+ */
+export declare function assertDshSessionEvent(value: unknown): DshSessionEvent;
+/** What a single dsh event means, in order. */
+export declare function dshEventToEvents(entry: TranscriptEntry): TranscriptEvent[];
+/** dsh's session-event log, as a registrable reader. */
+export declare const dshTranscriptReader: TranscriptReader;

package/transcript.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * DeepSeek Harness's transcript reader: dsh session events → neutral events.
+ *
+ * The read half of the adapter, and deliberately the only file in this package
+ * a renderer imports (`@agentic-kit/dsh/transcript`): it is browser-safe, has
+ * no dsh dependency and no db-tools dependency, so a dashboard can project a
+ * dsh run without pulling a node graph. `@agentic-kit/run-log` owns the neutral
+ * vocabulary and the registry; the format's meaning lives here, beside the
+ * adapter that produces it.
+ *
+ * dsh's log differs from pi's in three ways that matter:
+ * - it is an *event* log, not a message log: a tool call and its result are
+ *   separate events with their own sequence numbers, and a step boundary is an
+ *   event of its own;
+ * - `time` is epoch milliseconds, not an ISO string;
+ * - assistant reasoning is a `reasoning` content block, and a tool call's
+ *   arguments arrive as the raw JSON string the model produced.
+ *
+ * Register the reader once at host startup, e.g.
+ * `transcriptReaders.register(dshTranscriptReader)`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dshTranscriptReader = exports.SUPPORTED_DSH_TRANSCRIPT_VERSION = exports.DSH_TRANSCRIPT_FORMAT = void 0;
+exports.assertDshSessionEvent = assertDshSessionEvent;
+exports.dshEventToEvents = dshEventToEvents;
+const run_log_1 = require("@agentic-kit/run-log");
+/** dsh's session-event log (`@deepseek-ai/dsh-session`). */
+exports.DSH_TRANSCRIPT_FORMAT = 'dsh';
+/**
+ * dsh's `SESSION_FORMAT_VERSION` as of `0.1.0-rc.7`. It bumps only when the
+ * event envelope or the surface mechanism changes — a new event *type* does
+ * not bump it, which is why an unrecognized type here becomes an `unknown`
+ * event rather than a refusal.
+ */
+exports.SUPPORTED_DSH_TRANSCRIPT_VERSION = 0;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Narrow an untrusted dsh event. `seq` and `time` are part of dsh's envelope
+ * rather than optional decoration, so an entry missing them is not a dsh event
+ * and must not be stored as one.
+ */
+function assertDshSessionEvent(value) {
+    const entry = (0, run_log_1.assertTranscriptEntry)(value);
+    if (typeof entry.seq !== 'number' || !Number.isFinite(entry.seq)) {
+        throw new TypeError('dsh session event must carry a numeric `seq`');
+    }
+    if (typeof entry.time !== 'number' || !Number.isFinite(entry.time)) {
+        throw new TypeError('dsh session event must carry a numeric `time` (epoch ms)');
+    }
+    if (entry.data !== undefined && !isRecord(entry.data)) {
+        throw new TypeError('dsh session event `data` must be an object when present');
+    }
+    return entry;
+}
+/** What a single dsh event means, in order. */
+function dshEventToEvents(entry) {
+    const event = entry;
+    const data = isRecord(event.data) ? event.data : {};
+    const base = {
+        ...(typeof event.seq === 'number' ? { entryId: String(event.seq) } : {}),
+        ...(typeof event.time === 'number' ? { at: new Date(event.time).toISOString() } : {})
+    };
+    switch (event.type) {
+        case 'user/message': {
+            // A user-role event covers a human prompt and dsh's own injected context
+            // (file-change notices, skill content); `source.kind` tells them apart,
+            // and only a human one belongs in the conversation as a user turn.
+            const source = isRecord(data.source) ? data.source : {};
+            const text = blockText(data.content);
+            if (source.kind === 'user') {
+                return [{ kind: 'text', role: 'user', text, ...base }];
+            }
+            return [
+                {
+                    kind: 'custom',
+                    customType: `dsh.context.${String(source.kind ?? 'unknown')}`,
+                    text,
+                    display: false,
+                    ...(source.plugin === undefined ? {} : { details: { plugin: source.plugin } }),
+                    ...base
+                }
+            ];
+        }
+        case 'assistant/message': {
+            const message = isRecord(data.message) ? data.message : {};
+            const source = isRecord(message.source) ? message.source : {};
+            const model = typeof source.model === 'string' ? source.model : undefined;
+            const provider = typeof source.provider === 'string' ? source.provider : undefined;
+            const usage = tokenUsage(data.usage);
+            const events = [
+                {
+                    kind: 'model-response',
+                    ...(model ? { model } : {}),
+                    ...(provider ? { provider } : {}),
+                    ...(usage ? { usage } : {}),
+                    ...base
+                }
+            ];
+            for (const block of Array.isArray(message.content) ? message.content : []) {
+                if (!isRecord(block))
+                    continue;
+                if (block.type === 'text' && typeof block.text === 'string' && block.text.length > 0) {
+                    events.push({
+                        kind: 'text',
+                        role: 'assistant',
+                        text: block.text,
+                        ...(model ? { model } : {}),
+                        ...(provider ? { provider } : {}),
+                        ...base
+                    });
+                }
+                else if (block.type === 'reasoning' && typeof block.text === 'string') {
+                    events.push({ kind: 'thinking', text: block.text, ...base });
+                }
+                // A `tool-call` block is also logged as its own `tool/call` event, which
+                // is the one this reader projects — projecting both would double every
+                // call in a trace.
+            }
+            return events;
+        }
+        case 'tool/call':
+            return [
+                {
+                    kind: 'tool-call',
+                    toolCallId: String(data.callId ?? ''),
+                    name: String(data.name ?? ''),
+                    arguments: parseArguments(data.arguments),
+                    ...base
+                }
+            ];
+        case 'tool/result': {
+            const message = isRecord(data.message) ? data.message : {};
+            const block = (Array.isArray(message.content) ? message.content : []).find((candidate) => isRecord(candidate) && candidate.type === 'tool-result');
+            const source = isRecord(message.source) ? message.source : {};
+            const error = isRecord(data.error) ? data.error : undefined;
+            return [
+                {
+                    kind: 'tool-result',
+                    toolCallId: String(block?.toolCallId ?? source.callId ?? ''),
+                    // dsh's result carries the call id, not the tool name; a projector
+                    // pairs it with the `tool/call` that named it.
+                    name: '',
+                    output: blockText(block?.content),
+                    failed: block?.isError === true || error !== undefined,
+                    ...(data.meta === undefined ? {} : { details: data.meta }),
+                    ...base
+                }
+            ];
+        }
+        case 'approval/asked': {
+            const callId = typeof data.callId === 'string' ? data.callId : undefined;
+            const reason = typeof data.reason === 'string' ? data.reason : '';
+            if (!callId)
+                break;
+            return [
+                {
+                    kind: 'custom',
+                    customType: run_log_1.APPROVAL_REQUEST_TYPE,
+                    text: reason || `Approve ${String(data.toolName ?? 'tool call')}?`,
+                    display: true,
+                    details: { toolCallId: callId },
+                    ...base
+                }
+            ];
+        }
+        case 'approval/decided': {
+            const outcome = String(data.outcome ?? '');
+            return [
+                {
+                    kind: 'custom',
+                    customType: run_log_1.APPROVAL_RESOLUTION_TYPE,
+                    text: outcome,
+                    display: true,
+                    details: {
+                        // dsh pairs a decision with its ask by approval id; the request
+                        // carried the call id, so a projector joins through the ask.
+                        approvalId: data.id,
+                        decision: outcome === 'allowed-once' ? 'approved' : 'rejected',
+                        reason: outcome
+                    },
+                    ...base
+                }
+            ];
+        }
+        case 'compaction/summary':
+            return [
+                {
+                    kind: 'summary',
+                    reason: 'compaction',
+                    summary: typeof data.summary === 'string' ? data.summary : blockText(data.content),
+                    ...base
+                }
+            ];
+        case 'command/run':
+            return [
+                {
+                    kind: 'bash',
+                    command: String(data.command ?? ''),
+                    output: '',
+                    ...base
+                }
+            ];
+        case 'command/done':
+            return [
+                {
+                    kind: 'bash',
+                    command: String(data.command ?? ''),
+                    output: blockText(data.content) || String(data.output ?? ''),
+                    ...(typeof data.exitCode === 'number' ? { exitCode: data.exitCode } : {}),
+                    ...base
+                }
+            ];
+        // Token-level replay of an `assistant/message` that is projected in full.
+        case 'assistant/chunk':
+            return [];
+        default:
+            break;
+    }
+    return [{ kind: 'unknown', entryType: event.type, entry, ...base }];
+}
+/** dsh's session-event log, as a registrable reader. */
+exports.dshTranscriptReader = {
+    format: exports.DSH_TRANSCRIPT_FORMAT,
+    version: exports.SUPPORTED_DSH_TRANSCRIPT_VERSION,
+    assertEntry: assertDshSessionEvent,
+    toEvents: dshEventToEvents
+};
+/** The text of a dsh content-block array. */
+function blockText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((block) => {
+        if (!isRecord(block))
+            return '';
+        if (typeof block.text === 'string')
+            return block.text;
+        if (Array.isArray(block.content))
+            return blockText(block.content);
+        return '';
+    })
+        .filter((text) => text.length > 0)
+        .join('\n');
+}
+/**
+ * A tool call's arguments. dsh logs the raw JSON string the model produced, so
+ * a malformed call is *in* the log — it becomes the string it was rather than
+ * failing the whole entry.
+ */
+function parseArguments(value) {
+    if (isRecord(value))
+        return value;
+    if (typeof value !== 'string' || value.length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(value);
+        return isRecord(parsed) ? parsed : { value: parsed };
+    }
+    catch {
+        return { raw: value };
+    }
+}
+/**
+ * dsh's `TokenUsage` in the neutral vocabulary. Its input counts are disjoint
+ * — cached input is reported apart from `inputTokens` — so a total is the sum
+ * rather than the input field.
+ */
+function tokenUsage(value) {
+    if (!isRecord(value))
+        return undefined;
+    const input = numeric(value.inputTokens);
+    const output = numeric(value.outputTokens);
+    const cacheRead = numeric(value.cacheReadTokens);
+    const cacheWrite = numeric(value.cacheWriteTokens);
+    const usage = {
+        ...(input === undefined ? {} : { input }),
+        ...(output === undefined ? {} : { output }),
+        ...(cacheRead === undefined ? {} : { cacheRead }),
+        ...(cacheWrite === undefined ? {} : { cacheWrite })
+    };
+    if (Object.keys(usage).length === 0)
+        return undefined;
+    usage.totalTokens =
+        (input ?? 0) + (output ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
+    return usage;
+}
+const numeric = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;