@agentic-kit/dsh 0.2.0

package/esm/transcript.js

@@ -0,0 +1,285 @@
+/**
+ * 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 { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, assertTranscriptEntry } from '@agentic-kit/run-log';
+/** dsh's session-event log (`@deepseek-ai/dsh-session`). */
+export 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 const 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.
+ */
+export function assertDshSessionEvent(value) {
+    const entry = 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. */
+export 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: 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: 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. */
+export const dshTranscriptReader = {
+    format: DSH_TRANSCRIPT_FORMAT,
+    version: 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;

package/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@agentic-kit/dsh` — the DeepSeek Harness adapter.
+ *
+ * The sibling of `@agentic-kit/pi`, and the reason the harness contracts are
+ * neutral: the same 18 Constructive tools, the same confirm gate and the same
+ * run-log vocabulary, bound to a second harness without any of them changing.
+ * Everything dsh-specific is here — its tool shape, its JSON Schema subset, its
+ * plugin surface, its session-event log — and nothing here reaches back into
+ * the neutral packages' internals.
+ *
+ * dsh is a developer preview whose packages promise breaking changes, so this
+ * adapter binds to its *shape* rather than its types (see `./dsh-types`): the
+ * package has no `@deepseek-ai/*` dependency, which also keeps dsh's ESM-only
+ * graph out of a CJS consumer's way.
+ */
+export { toDshTool, type ToDshToolOptions, toDshTools } from './dsh-tool';
+export { type DshApprovalOutcome, type DshApprovalService, type DshContentBlock, type DshJsonSchema, type DshPlugin, type DshPluginContext, type DshPreToolDecision, type DshToolDefinition, type DshToolExecution, type DshToolOutputDefinition, type DshToolRunContext, type DshToolRuntime } from './dsh-types';
+export { type ConstructivePluginOptions, createConstructivePlugin, DSH_PLUGIN_NAME } from './plugin';
+export { convertDshParameters, type DshSchemaConversion, toDshParameters } from './schema';
+/**
+ * The transcript reader, re-exported for a node host. A renderer imports
+ * `@agentic-kit/dsh/transcript` instead: that entry point pulls neither the db
+ * tools nor anything else a browser cannot load.
+ */
+export { assertDshSessionEvent, DSH_TRANSCRIPT_FORMAT, dshEventToEvents, type DshSessionEvent, dshTranscriptReader, SUPPORTED_DSH_TRANSCRIPT_VERSION } from './transcript';
+/** Stable adapter id, matching the transcript format its runs are logged under. */
+export declare const DSH_HARNESS_ID = "dsh";

package/index.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * `@agentic-kit/dsh` — the DeepSeek Harness adapter.
+ *
+ * The sibling of `@agentic-kit/pi`, and the reason the harness contracts are
+ * neutral: the same 18 Constructive tools, the same confirm gate and the same
+ * run-log vocabulary, bound to a second harness without any of them changing.
+ * Everything dsh-specific is here — its tool shape, its JSON Schema subset, its
+ * plugin surface, its session-event log — and nothing here reaches back into
+ * the neutral packages' internals.
+ *
+ * dsh is a developer preview whose packages promise breaking changes, so this
+ * adapter binds to its *shape* rather than its types (see `./dsh-types`): the
+ * package has no `@deepseek-ai/*` dependency, which also keeps dsh's ESM-only
+ * graph out of a CJS consumer's way.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DSH_HARNESS_ID = exports.SUPPORTED_DSH_TRANSCRIPT_VERSION = exports.dshTranscriptReader = exports.dshEventToEvents = exports.DSH_TRANSCRIPT_FORMAT = exports.assertDshSessionEvent = exports.toDshParameters = exports.convertDshParameters = exports.DSH_PLUGIN_NAME = exports.createConstructivePlugin = exports.toDshTools = exports.toDshTool = void 0;
+var dsh_tool_1 = require("./dsh-tool");
+Object.defineProperty(exports, "toDshTool", { enumerable: true, get: function () { return dsh_tool_1.toDshTool; } });
+Object.defineProperty(exports, "toDshTools", { enumerable: true, get: function () { return dsh_tool_1.toDshTools; } });
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "createConstructivePlugin", { enumerable: true, get: function () { return plugin_1.createConstructivePlugin; } });
+Object.defineProperty(exports, "DSH_PLUGIN_NAME", { enumerable: true, get: function () { return plugin_1.DSH_PLUGIN_NAME; } });
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "convertDshParameters", { enumerable: true, get: function () { return schema_1.convertDshParameters; } });
+Object.defineProperty(exports, "toDshParameters", { enumerable: true, get: function () { return schema_1.toDshParameters; } });
+/**
+ * The transcript reader, re-exported for a node host. A renderer imports
+ * `@agentic-kit/dsh/transcript` instead: that entry point pulls neither the db
+ * tools nor anything else a browser cannot load.
+ */
+var transcript_1 = require("./transcript");
+Object.defineProperty(exports, "assertDshSessionEvent", { enumerable: true, get: function () { return transcript_1.assertDshSessionEvent; } });
+Object.defineProperty(exports, "DSH_TRANSCRIPT_FORMAT", { enumerable: true, get: function () { return transcript_1.DSH_TRANSCRIPT_FORMAT; } });
+Object.defineProperty(exports, "dshEventToEvents", { enumerable: true, get: function () { return transcript_1.dshEventToEvents; } });
+Object.defineProperty(exports, "dshTranscriptReader", { enumerable: true, get: function () { return transcript_1.dshTranscriptReader; } });
+Object.defineProperty(exports, "SUPPORTED_DSH_TRANSCRIPT_VERSION", { enumerable: true, get: function () { return transcript_1.SUPPORTED_DSH_TRANSCRIPT_VERSION; } });
+/** Stable adapter id, matching the transcript format its runs are logged under. */
+exports.DSH_HARNESS_ID = 'dsh';

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agentic-kit/dsh",
+  "version": "0.2.0",
+  "author": "Dan Lynch <pyramation@gmail.com>",
+  "description": "the DeepSeek Harness adapter for agentic-kit — Constructive's typed db tools and confirm gate as a dsh plugin, plus a dsh transcript reader for the run log",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@agentic-kit/db-tools": "^0.3.0",
+    "@agentic-kit/harness": "^0.15.0",
+    "@agentic-kit/run-log": "^0.6.0",
+    "zod": "^4.4.3"
+  },
+  "keywords": [
+    "agentic-kit",
+    "harness",
+    "adapter",
+    "dsh",
+    "deepseek",
+    "constructive"
+  ],
+  "gitHead": "e35db12526094b515596ced2dd27a1ec8edd99d5"
+}

package/plugin.d.ts

@@ -0,0 +1,37 @@
+import { type ToolsHost } from '@agentic-kit/db-tools';
+import type { AnyHarnessTool, ConfirmGateOptions } from '@agentic-kit/harness';
+import type { DshPlugin } from './dsh-types';
+export interface ConstructivePluginOptions {
+    /** Tools to register. Defaults to the whole `constructiveDbTools` set. */
+    tools?: readonly AnyHarnessTool[];
+    /**
+     * The directory the run is rooted at — the project a tool resolves its
+     * context and credentials from. Defaults to `process.cwd()`.
+     */
+    cwd?: () => string;
+    /**
+     * The gate in front of a mutating call. Defaults to Constructive's database
+     * policy; pass `false` for a host that gates elsewhere (its own
+     * `tools/pre-execute` listener, a hook, an approval preset).
+     */
+    gate?: ConfirmGateOptions | false;
+    /** The db tools' host contract, when it is not configured already. */
+    host?: ToolsHost;
+}
+export declare const DSH_PLUGIN_NAME = "constructive-tools";
+/**
+ * Constructive's tools as a dsh plugin.
+ *
+ * The sibling of `@agentic-kit/pi`'s `dbTools` extension: the same neutral
+ * tools, registered through dsh's own registry, with the same host-neutral
+ * confirm gate wired to dsh's `tools/pre-execute` waterfall instead of pi's
+ * `tool_call` event. Nothing Constructive-specific is duplicated — the tools,
+ * the gate policy and the decline memory all come from the neutral packages.
+ *
+ * A `deny` decision is dsh's own vocabulary for "this call does not run, and
+ * here is what to tell the model", which is exactly what the gate returns; an
+ * approval question goes to dsh's approval service when the host composed one,
+ * so a headless dsh run refuses a gated call rather than performing it
+ * unasked.
+ */
+export declare function createConstructivePlugin(options?: ConstructivePluginOptions): DshPlugin;

package/plugin.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DSH_PLUGIN_NAME = void 0;
+exports.createConstructivePlugin = createConstructivePlugin;
+const db_tools_1 = require("@agentic-kit/db-tools");
+const harness_1 = require("@agentic-kit/harness");
+const dsh_tool_1 = require("./dsh-tool");
+exports.DSH_PLUGIN_NAME = 'constructive-tools';
+/**
+ * Constructive's tools as a dsh plugin.
+ *
+ * The sibling of `@agentic-kit/pi`'s `dbTools` extension: the same neutral
+ * tools, registered through dsh's own registry, with the same host-neutral
+ * confirm gate wired to dsh's `tools/pre-execute` waterfall instead of pi's
+ * `tool_call` event. Nothing Constructive-specific is duplicated — the tools,
+ * the gate policy and the decline memory all come from the neutral packages.
+ *
+ * A `deny` decision is dsh's own vocabulary for "this call does not run, and
+ * here is what to tell the model", which is exactly what the gate returns; an
+ * approval question goes to dsh's approval service when the host composed one,
+ * so a headless dsh run refuses a gated call rather than performing it
+ * unasked.
+ */
+function createConstructivePlugin(options = {}) {
+    const cwd = options.cwd ?? (() => process.cwd());
+    const tools = options.tools ?? db_tools_1.constructiveDbTools;
+    if (options.host)
+        (0, db_tools_1.configureHost)(options.host);
+    return {
+        name: exports.DSH_PLUGIN_NAME,
+        inject: ['tools'],
+        apply(ctx) {
+            for (const definition of (0, dsh_tool_1.toDshTools)(tools, { cwd })) {
+                ctx.tools.register(definition);
+            }
+            if (options.gate === false)
+                return;
+            const gate = (0, harness_1.createConfirmGate)(options.gate ?? (0, db_tools_1.constructiveGateDeps)());
+            ctx.on('tools/pre-execute', async (exec, next) => {
+                const result = await gate.onToolCall({
+                    toolName: exec.name,
+                    toolCallId: exec.callId,
+                    input: (exec.arguments ?? undefined)
+                }, approvalHost(ctx.approval, exec), cwd());
+                if (result?.block)
+                    return { kind: 'deny', reason: result.reason };
+                return next();
+            });
+        }
+    };
+}
+/**
+ * dsh's approval service as the gate's host. `allowed-once` is the only
+ * outcome that approves — `rejected`, `cancelled` and the fail-closed
+ * `unavailable` all decline — and a host with no approval service composed has
+ * no confirm surface at all, which the gate answers by blocking.
+ */
+function approvalHost(approval, exec) {
+    return {
+        hasUI: approval !== undefined,
+        confirmTool: async (_toolCallId, title, message) => {
+            if (!approval)
+                return false;
+            const outcome = await approval.request({
+                toolName: exec.name,
+                callId: exec.callId,
+                reason: `${title}\n\n${message}`,
+                ...(exec.agent === undefined ? {} : { agent: exec.agent })
+            });
+            return outcome === 'allowed-once';
+        },
+        // dsh records the ask and its outcome itself (`approval/asked`,
+        // `approval/decided`), so an auto-skipped retry needs no separate notice.
+        notifyToolSkipped: () => undefined
+    };
+}

package/schema.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import type { DshJsonSchema } from './dsh-types';
+/** What a conversion dropped, so a caller can log it rather than wonder. */
+export interface DshSchemaConversion {
+    parameters: DshJsonSchema;
+    /**
+     * Keywords dropped from the model-facing schema, as JSON-pointer-ish paths
+     * (`properties.rows.minItems`). Still enforced by zod at execute time.
+     */
+    dropped: string[];
+}
+/** Convert and report, for a host that wants to see what degraded. */
+export declare function convertDshParameters(schema: z.ZodType): DshSchemaConversion;
+/** The dsh-subset JSON Schema for a tool's parameters. */
+export declare const toDshParameters: (schema: z.ZodType) => DshJsonSchema;