@agentic-kit/dsh 0.2.0

package/esm/dsh-types.js

@@ -0,0 +1,18 @@
+/**
+ * The DeepSeek Harness surface this adapter binds to, declared structurally.
+ *
+ * Nothing here imports `@deepseek-ai/dsh-*`, and the package has no dependency
+ * on it. That is deliberate rather than lazy: dsh is a developer preview whose
+ * packages promise breaking changes, and its published rc's trail its own
+ * source. A structural declaration of the four things we actually touch — a
+ * tool definition, a tool's run context, a content block, a plugin's `apply` —
+ * binds to the *shape* dsh asks for, so a host on any rc can register our tools
+ * without this package tracking their release train. It also keeps the adapter
+ * free of dsh's ESM-only graph: a CJS consumer imports it like any other
+ * agentic-kit package.
+ *
+ * Mirrored from dsh `0.1.0-rc.7` (`packages/core/tools`, `packages/core/session`,
+ * `packages/llm/llm`). Where dsh brands a string (`CallId`, `SessionId`) this
+ * uses `string` — a brand is theirs to enforce, and ours to carry.
+ */
+export {};

package/esm/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/esm/index.js

@@ -0,0 +1,26 @@
+/**
+ * `@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, toDshTools } from './dsh-tool';
+export { createConstructivePlugin, DSH_PLUGIN_NAME } from './plugin';
+export { convertDshParameters, 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, dshTranscriptReader, SUPPORTED_DSH_TRANSCRIPT_VERSION } from './transcript';
+/** Stable adapter id, matching the transcript format its runs are logged under. */
+export const DSH_HARNESS_ID = 'dsh';

package/esm/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/esm/plugin.js

@@ -0,0 +1,72 @@
+import { configureHost, constructiveDbTools, constructiveGateDeps } from '@agentic-kit/db-tools';
+import { createConfirmGate } from '@agentic-kit/harness';
+import { toDshTools } from './dsh-tool';
+export 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 function createConstructivePlugin(options = {}) {
+    const cwd = options.cwd ?? (() => process.cwd());
+    const tools = options.tools ?? constructiveDbTools;
+    if (options.host)
+        configureHost(options.host);
+    return {
+        name: DSH_PLUGIN_NAME,
+        inject: ['tools'],
+        apply(ctx) {
+            for (const definition of toDshTools(tools, { cwd })) {
+                ctx.tools.register(definition);
+            }
+            if (options.gate === false)
+                return;
+            const gate = createConfirmGate(options.gate ?? 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/esm/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;

package/esm/schema.js

@@ -0,0 +1,148 @@
+import { z } from '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. */
+export 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 = 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. */
+export const toDshParameters = (schema) => convertDshParameters(schema).parameters;

package/esm/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;