@maci0/dsh-caveman 0.16.2

package/lib/types/host.d.ts

@@ -0,0 +1,201 @@
+/**
+ * The slice of the DeepSeek Harness host surface this plugin uses, declared
+ * structurally.
+ *
+ * The plugin is installed from outside the harness checkout. It depends on the
+ * published `@deepseek-ai/dsh-tools` and `@deepseek-ai/dsh-skill` packages: the
+ * skill domain shapes (summaries, candidates, definitions, lookup options) are
+ * imported from the latter, while the services it reaches through
+ * `ctx.inject([...])` are declared structurally here: the host types remain
+ * authoritative, and a composition that does not mount a service simply omits
+ * that capability.
+ *
+ * @module dsh-caveman/host
+ */
+import type { SkillCandidate, SkillDefinition, SkillLookupOptions, SkillProviderObservation } from '@deepseek-ai/dsh-skill';
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+/** Disposer returned by every host registration. */
+type Disposable = () => void;
+/** One contributed system-prompt section. */
+export interface PromptSectionContribution {
+    /** Unique section name across the composition. */
+    readonly name: string;
+    /** Ascending concatenation position. */
+    readonly order: number;
+    /** Static text, or a provider evaluated at each assembly (empty text is dropped). */
+    readonly text: string | ((context: unknown) => string);
+}
+/**
+ * The workspace-independent slice of the host's `SkillProvider` this plugin
+ * implements: native discovery observations, with lookup options optional for
+ * direct callers. The packaged provider ignores `cwd`.
+ */
+export interface SkillProviderLike {
+    /** Unique provider name in the registry. */
+    readonly name: string;
+    /** List candidates for the current lookup, settling promptly on abort. */
+    list(options?: SkillLookupOptions): Promise<readonly SkillCandidate[] | SkillProviderObservation>;
+    /** Load a winning candidate's body, or `undefined` when it is gone. */
+    get(candidate: SkillCandidate, options?: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+}
+/** The slice of the calling agent this plugin reads. */
+export interface AgentLike {
+    /** The agent's session; its header carries the workspace a relative path means. */
+    readonly session?: {
+        readonly header?: {
+            readonly cwd?: string | undefined;
+        } | undefined;
+    } | undefined;
+}
+/** The slice of a tool execution context this plugin reads. */
+export interface ToolExecLike {
+    /** The agent on whose behalf the call runs. */
+    readonly agent?: AgentLike | undefined;
+    /** Caller-owned cancellation for this invocation. */
+    readonly signal?: AbortSignal | undefined;
+}
+/** One session-projection unit state. */
+export interface ProjectionStateLike {
+    /** Cumulative provider-reported token buckets, named as the unit names them. */
+    readonly totals?: {
+        readonly uncachedInputTokens?: number;
+        readonly outputTokens?: number;
+        readonly cacheReadTokens?: number;
+        readonly cacheWriteTokens?: number;
+    } | undefined;
+}
+/** The slice of the session-projections service this plugin reads. */
+export interface SessionProjectionsLike {
+    /** Read one unit's host state for a session, or `undefined` when absent. */
+    stateOf(session: unknown, key: string): ProjectionStateLike | undefined;
+}
+/** Invocation handed to a registered human command. */
+export interface CommandInvocationLike {
+    /** Text following the command name, including separator whitespace. */
+    readonly rawInput: string;
+    /** The agent whose UI received the command. */
+    readonly agent?: AgentLike | undefined;
+}
+/** Direct-UI outcome of a human command. */
+export type CommandResultLike = {
+    readonly kind: 'success';
+    readonly text?: string;
+} | {
+    readonly kind: 'error';
+    readonly text: string;
+};
+/** A plugin-owned human command. */
+export interface CommandDefinitionLike {
+    /** Lowercase command name without the leading slash. */
+    readonly name: string;
+    /** Summary used in discovery UI. */
+    readonly description: string;
+    /** Optional free-form input hint. */
+    readonly input?: {
+        readonly hint: string;
+    };
+    /** Execute against the receiving agent without a model message. */
+    handler(invocation: CommandInvocationLike): CommandResultLike | Promise<CommandResultLike>;
+}
+/**
+ * The slice of a durable session message the deactivation watcher reads.
+ *
+ * `source.kind === 'user'` is what separates the human's own words from the
+ * context the harness injects into the same event stream (skill bodies,
+ * references, replayed history).
+ */
+export interface SessionMessageLike {
+    /** Content blocks; only `text` blocks carry words. */
+    readonly content?: readonly {
+        readonly type?: string;
+        readonly text?: string;
+    }[] | undefined;
+    /** Provenance of the message. */
+    readonly source?: {
+        readonly kind?: string;
+    } | undefined;
+}
+/** One durable session event, as `session/event` delivers it. */
+export interface SessionEventLike {
+    /** Event discriminator, e.g. `user/message`. */
+    readonly type?: string;
+    /** Event payload; a {@link SessionMessageLike} for `user/message`. */
+    readonly data?: unknown;
+}
+/**
+ * Structural view of the Cordis context the plugin uses.
+ *
+ * Members are only reached inside the matching `inject` callback, where the
+ * host guarantees the service is present.
+ */
+export interface HostContext {
+    /** Run `callback` once the named services are available. */
+    inject(dependencies: readonly string[], callback: (scope: HostContext) => void): unknown;
+    /** Bind a registration's disposer to the calling fiber. */
+    effect(callback: () => Disposable, label?: string): unknown;
+    /** Subscribe to a host event; the returned disposer removes the listener. */
+    on(event: 'session/event', listener: (session: unknown, event: SessionEventLike) => void): Disposable;
+    on(event: 'loader/volatile-update', listener: () => void): Disposable;
+    /** Read one mounted service. `undefined` when that service is absent. */
+    get(name: 'settings'): SettingsServiceLike | undefined;
+    get(name: 'sessionProjections'): SessionProjectionsLike | undefined;
+    /** Owning fiber, present once the loader mounted this plugin. */
+    readonly fiber?: {
+        readonly entry?: {
+            readonly options?: {
+                readonly id?: string;
+            };
+        };
+    };
+    readonly systemPrompt: {
+        section(section: PromptSectionContribution): Disposable;
+    };
+    readonly skills: {
+        registerProvider(create: () => SkillProviderLike): Disposable;
+    };
+    readonly tools: {
+        register(definition: ToolDefinition): Disposable;
+    };
+    readonly commands: {
+        register(definition: CommandDefinitionLike): Disposable;
+    };
+    readonly webServer: WebServerLike;
+    readonly connection: ConnectionLike;
+}
+/** The slice of an incoming HTTP request the level route reads. */
+export interface RequestLike {
+    readonly method?: string | undefined;
+    readonly headers: object | undefined;
+}
+/** The slice of an HTTP response the level route writes. */
+export interface ResponseLike {
+    statusCode: number;
+    setHeader(name: string, value: string): void;
+    end(body?: string): void;
+}
+/** The slice of the `webServer` service this plugin registers on. */
+export interface WebServerLike {
+    /** Register one route; a duplicate path throws. */
+    register(route: {
+        readonly kind: 'exact';
+        readonly path: string;
+        handler(req: RequestLike, res: ResponseLike): void | Promise<void>;
+    }): Disposable;
+}
+/** The composition's trust fence for HTTP requests. */
+export interface ConnectionLike {
+    /** The rejection status for an untrusted or unauthenticated request, else `undefined`. */
+    requestRejection(request: {
+        readonly headers: object | undefined;
+    }): 401 | 403 | undefined;
+}
+/** The slice of the settings service this plugin uses. */
+export interface SettingsServiceLike {
+    /**
+     * Merge fields into one profile entry. `ns` is the entry id, not a namespace.
+     * @param ns - profile entry id.
+     * @param patch - fields to merge.
+     */
+    update(ns: string, patch: Record<string, unknown>): Promise<void>;
+}
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * dsh-caveman: Caveman terse-talk mode, as a DeepSeek Harness plugin.
+ *
+ * Four capabilities, all mounted through public Cordis extension points:
+ *
+ * - the bundled skills (`caveman`, `cavecrew`, `-commit`, `-review`,
+ *   `-compress`, `-stats`, `-help`, plus six work patterns) become one
+ *   `ctx.skills` provider;
+ * - while a level other than `off` is active, the mode-filtered ruleset is
+ *   contributed to the system prompt on every assembly;
+ * - the level is switchable from the model (`caveman` tool) and the human
+ *   (`/caveman` command);
+ * - the `caveman` settings namespace makes the level persistent and pairs with
+ *   this package's browser half, which renders the card in the Web client's
+ *   Plugins page, on the caveman row's Configure control.
+ *
+ * Skill content is adapted from the reference implementation
+ * (https://github.com/JuliusBrussee/caveman, MIT, © JuliusBrussee). Only the
+ * skill (talking-style) half is ported: the proxy, CLI verbs, and Cloud
+ * engine need an external runtime the harness has no extension point for.
+ *
+ * @module dsh-caveman
+ */
+import type { Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type CavemanMode } from './modes.ts';
+import type { HostContext } from './host.ts';
+/** Plugin name as it appears in the loader. */
+export declare const name = "caveman";
+/**
+ * Route the browser half reads for the level in use and its source. The card
+ * and the chip cannot see the env, the upstream config file, or a
+ * session-local level, so they ask the host instead of the settings document.
+ */
+export declare const LEVEL_ROUTE = "/caveman/level";
+/**
+ * Configuration received by the plugin, as the loader resolved this row
+ * against the schema below: every ordinary field carries its default, and every
+ * volatile field arrives as the live reference the settings document writes
+ * through. Read `.get()` when starting an operation.
+ */
+export interface Config {
+    /** Startup level. Absent resolves through the chain, ending at `full`. */
+    readonly defaultMode: Volatile<CavemanMode | undefined>;
+    /**
+     * Size cap in bytes for `/caveman-compress`; defaults to 500000. Volatile,
+     * so the Plugins card can raise or lower it while the plugin runs.
+     */
+    readonly maxFileSize: Volatile<number>;
+}
+/**
+ * Row schema: the accepted levels and the size cap live here.
+ *
+ * Both fields are volatile, the only kind the settings document accepts: a
+ * change commits into the running config without remounting the plugin. Each is
+ * read at the moment it is used (the level at every prompt assembly, the size
+ * cap at every compress call), so an edit from the Plugins card takes effect on
+ * the next use rather than on a restart.
+ *
+ * `defaultMode` carries no default, so absence keeps flowing to
+ * `resolveDefaultMode`. A schema default would fill the field before `apply`,
+ * which would silently outrank `CAVEMAN_DEFAULT_MODE` and
+ * `~/.config/caveman/config.json`.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    defaultMode: z<"full" | "lite" | "off" | "ultra" | "wenyan-full" | "wenyan-lite" | "wenyan-ultra", "full" | "lite" | "off" | "ultra" | "wenyan-full" | "wenyan-lite" | "wenyan-ultra", "volatile">;
+    maxFileSize: z<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    defaultMode: z<"full" | "lite" | "off" | "ultra" | "wenyan-full" | "wenyan-lite" | "wenyan-ultra", "full" | "lite" | "off" | "ultra" | "wenyan-full" | "wenyan-lite" | "wenyan-ultra", "volatile">;
+    maxFileSize: z<number, number, "volatile-defined">;
+}>>, "plain">;
+/**
+ * Read the upstream config file's `defaultMode`, ignoring everything that
+ * would make startup fail: a missing file, an unreadable file, invalid JSON,
+ * or a non-object document all mean "no file default".
+ * @param path - config file path; the upstream location unless tests override it.
+ * @returns the parsed document, or `undefined` when there is nothing usable.
+ */
+export declare function readUpstreamConfigFile(path?: string): {
+    readonly defaultMode?: unknown;
+} | undefined;
+/**
+ * Mount the plugin.
+ * @param ctx - the host context.
+ * @param config - the schema-resolved row configuration.
+ */
+export declare function apply(ctx: HostContext, config: Config): void;

package/lib/types/modes.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Caveman's level model: the accepted levels, their normalization, the
+ * mode-specific filter over the `caveman` skill body, and the instruction
+ * block the plugin injects into the system prompt.
+ *
+ * Levels mirror upstream (`JuliusBrussee/caveman`, MIT): lite, full, ultra
+ * and the three wenyan variants. Unlike ponytail there is no session-only
+ * level: every level persists. The one addition over upstream is the
+ * `wenyan` shorthand for `wenyan-full`, accepted by the `/caveman` command.
+ *
+ * @module dsh-caveman/modes
+ */
+/** Every accepted level; all persist as a default. */
+export declare const RUNTIME_MODES: readonly ['off', 'lite', 'full', 'ultra', 'wenyan-lite', 'wenyan-full', 'wenyan-ultra'];
+/** Any level the plugin accepts. */
+export type CavemanMode = (typeof RUNTIME_MODES)[number];
+/** Level used when neither config nor environment sets one. */
+export declare const DEFAULT_MODE: CavemanMode;
+/**
+ * Normalize a value to a level that may be persisted as a default.
+ * @param value - candidate level from a config field, environment, or command.
+ * @returns the canonical runtime level, or `undefined` when unrecognized.
+ */
+export declare function normalizeMode(value: unknown): CavemanMode | undefined;
+/**
+ * Whether a whole message is a deactivation command.
+ *
+ * "stop caveman" / "normal mode" turn caveman off, but only as a standalone
+ * command: matching the phrase anywhere in a message turned it off mid-task for
+ * ordinary requests like "add a normal mode toggle", so the whole trimmed
+ * message must be the command, ignoring case and trailing punctuation.
+ * @param text - user message text.
+ * @returns whether the message is the deactivation command.
+ */
+export declare function isDeactivationCommand(text: string): boolean;
+/**
+ * Resolve a human `/caveman` argument to a level, including the `wenyan`
+ * shorthand for `wenyan-full` (upstream: `/caveman wenyan` means full 文言文).
+ * @param input - trimmed, lowercased command input.
+ * @returns the canonical level, or `undefined` when unrecognized.
+ */
+export declare function normalizeCommandMode(input: string): CavemanMode | undefined;
+/**
+ * Where the level in use came from: the row's `defaultMode` (which the
+ * settings document edits), `CAVEMAN_DEFAULT_MODE`, the upstream config file,
+ * the built-in `full`, or a level held only by this process because the
+ * settings document could not take it.
+ */
+export type LevelSource = 'settings' | 'env' | 'config-file' | 'default' | 'session';
+/** A level together with the source that decided it. */
+export interface ResolvedLevel {
+    readonly mode: CavemanMode;
+    readonly source: LevelSource;
+}
+/** Inputs for {@link resolveDefaultMode}, all injectable for tests. */
+interface DefaultModeSources {
+    /** Deployment default from this plugin's config field; wins over everything. */
+    readonly configured?: unknown;
+    /** Environment lookup; defaults to `process.env`. */
+    readonly env?: Record<string, string | undefined> | undefined;
+    /** Parsed upstream config file (`~/.config/caveman/config.json`); lowest config priority. */
+    readonly configFile?: {
+        readonly defaultMode?: unknown;
+    } | undefined;
+}
+/**
+ * Resolve the configured level and the source that decided it.
+ *
+ * Order: this plugin's config field, then `CAVEMAN_DEFAULT_MODE`, then the
+ * upstream config file (`~/.config/caveman/config.json`), then `full`.
+ * @param sources - injectable overrides for tests.
+ * @returns the level and its source.
+ */
+export declare function resolveDefaultMode(sources?: DefaultModeSources): ResolvedLevel;
+/**
+ * Drop the intensity-table rows and worked examples that belong to other
+ * levels.
+ *
+ * Only the intensity table rows and worked examples are mode-specific, and both
+ * are keyed by a level name. A bullet whose label is not a level (e.g.
+ * "Never drop not/never/no/only/except ...") is a normal rule and stays
+ * verbatim; the quoted-value requirement on examples is what keeps a rule that
+ * merely starts with a level word from being dropped in every other mode.
+ * @param body - markdown of the `caveman` skill, frontmatter already removed.
+ * @param mode - the level to keep.
+ * @returns the body with other levels' rows and examples removed.
+ */
+export declare function filterSkillBodyForMode(body: string, mode: CavemanMode): string;
+/** Inputs for {@link buildModeInstructions}. */
+interface InstructionInput {
+    /** Active level. */
+    readonly mode: CavemanMode;
+    /** `skills/caveman/SKILL.md` body with its frontmatter already removed. */
+    readonly skillBody: string;
+}
+/**
+ * Build the exact text the system prompt carries for one level.
+ * @param input - the active level and the skill body.
+ * @returns the instruction block, or `''` when the level is `off`.
+ */
+export declare function buildModeInstructions(input: InstructionInput): string;
+export {};

package/lib/types/skills.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The bundled caveman skills as a `ctx.skills` provider.
+ *
+ * Skills are read from this package's `skills/<name>/SKILL.md`, so the same
+ * files stay the single source of truth for both the always-on ruleset (which
+ * filters the `caveman` body per level) and the on-demand skills.
+ *
+ * @module dsh-caveman/skills
+ */
+import type { SkillInvocationPolicy } from '@deepseek-ai/dsh-skill';
+import type { SkillProviderLike } from './host.ts';
+/** One parsed bundled skill. */
+interface CavemanSkill {
+    /** Kebab-case skill name from frontmatter, or the directory name. */
+    readonly name: string;
+    /** Routing description from frontmatter. */
+    readonly description: string;
+    /** Optional extra routing guidance from `whenToUse`. */
+    readonly whenToUse?: string;
+    /** Resolved invocation controls from the two canonical frontmatter keys. */
+    readonly invocation: SkillInvocationPolicy;
+    /** Instruction body with frontmatter removed. */
+    readonly content: string;
+    /** Frontmatter keys this provider does not project (`license`, `tools`, …). */
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /** Absolute path of the instruction file. */
+    readonly path: string;
+    /** Absolute path of the skill directory, used as the resource base. */
+    readonly directory: string;
+}
+/** Options for {@link createSkillProvider}. */
+interface SkillProviderOptions {
+    /** Directory holding one subdirectory per skill. */
+    readonly skillsDir: string;
+    /** Receives non-fatal discovery problems instead of throwing. */
+    readonly onWarn?: (message: string) => void;
+}
+/**
+ * Read every valid skill directory under `skillsDir`.
+ *
+ * A missing directory, a directory without `SKILL.md`, a file whose frontmatter
+ * the reader refuses, and a file with a missing description are reported
+ * through `onWarn` and skipped: one broken file must not cost the catalog its
+ * other skills.
+ * @param skillsDir - directory holding one subdirectory per skill.
+ * @param onWarn - optional non-fatal problem sink.
+ * @returns the parsed skills, sorted by name.
+ */
+export declare function discoverSkills(skillsDir: string, onWarn?: (message: string) => void): Promise<readonly CavemanSkill[]>;
+/**
+ * Build the provider the skill registry mounts.
+ * @param options - skills directory and the non-fatal problem sink.
+ * @returns a provider whose candidates are summaries and whose bodies come from disk.
+ */
+export declare function createSkillProvider(options: SkillProviderOptions): SkillProviderLike;
+export {};

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Caveman",
+    "description": "Terse-talk mode with bundled skills and a compression ruleset."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "简言",
+    "description": "简言模式：附带技能与压缩规则，让回复更短。"
+  }
+}

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@maci0/dsh-caveman",
+  "version": "0.16.2",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "description": "Caveman terse-talk mode, for DeepSeek Harness: bundled skills, an always-on compression ruleset, and a Plugin configuration card.",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
+      ]
+    },
+    "compatibility": {
+      "dsh": ">=0.2.0-rc.2 <0.3.0"
+    }
+  },
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "skills",
+    "scripts/sync-upstream.mjs",
+    "sync.manifest.json",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bunx --bun tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "bunx --bun tsc -p tsconfig.json",
+    "sync:check": "bun scripts/sync-upstream.mjs check",
+    "sync": "bun scripts/sync-upstream.mjs sync",
+    "test:node": "node --test tests/*.test.*"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-skill": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "yaml": "2.9.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-client-connection": "*",
+    "@deepseek-ai/dsh-client-locale": "*",
+    "@deepseek-ai/dsh-client-ui-renderer": "*",
+    "@deepseek-ai/dsh-client-ui-settings": "*",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-connection": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-renderer": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-plugin-manager": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-brand": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.1",
+    "@types/node": "^22.20.2",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maci0/dsh-caveman.git"
+  },
+  "icon": "./icon.svg"
+}