@zlnap/astrolabe 0.16.0 → 0.17.0

package/lib/setup/vendor/astrolabe-dsh-guard/README.md

@@ -0,0 +1,93 @@
+# astrolabe-dsh-guard — Astrolabe drift guard for DeepSeek Harness
+
+A **native DeepSeek Harness (DSH) hook plugin** that runs `astrolabe hooks remind`
+on every relevant tool call and denies the call when Astrolabe says the agent has
+drifted into repeated `grep`/`read` instead of using Astrolabe's MCP tools.
+
+Unlike the Claude Code marketplace plugin in `../claude-plugin` (which only
+registers the MCP server), this package is for **DSH hosts**, whose hook surface
+is a Cordis plugin API rather than a `hooks.json` file.
+
+## Why a native plugin
+
+DSH's own design note is explicit:
+
+> "native hooks" are not a package — a native hook is just an ordinary Cordis
+> plugin subscribing to the canonical lifecycle events. … Anything a bridge can
+> do, a plain plugin can do directly — more powerfully (no serialization
+> boundary, full `ctx`, typed returns).
+
+Running Astrolabe's hook through `@deepseek-ai/dsh-hooks-claude-code` also works,
+but that path needs a third-party bridge package, a `hooks.json`, and a wrapper
+script. This plugin needs none of them.
+
+## Requirements
+
+- `astrolabe` on `PATH` (see the repository README), or set `config.binary` to an
+  absolute path.
+- A DSH profile where the plugin can be loaded (see *Install* below).
+
+## Install
+
+```bash
+# 1. put the package where the DSH profile resolves modules
+cp -R dsh-plugin "$HOME/.dsh/profiles/desktop/node_modules/astrolabe-dsh-guard"
+```
+
+```yaml
+# 2. ~/.dsh/cordis.patch.yml — insert the plugin
+- insert:
+    - id: astrolabe-guard
+      name: 'astrolabe-dsh-guard'
+      config:
+        client: claude-code
+```
+
+DSH hot-reloads the patch file; no restart is required.
+
+> The package declares `dsh.bundle`, so a DSH plugin manager that installs
+> bundles can also take it (from a git URL or a local path) and manage it as a
+> normal entry.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `binary` | `astrolabe` | Executable to run; an absolute path is safest |
+| `client` | `claude-code` | `--client` dialect passed to `astrolabe hooks remind` |
+| `timeoutMs` | `20000` | Per-call timeout for the hook process |
+| `stateDir` | `<tmpdir>/astrolabe-dsh-guard` | `HOME` for the hook process; Astrolabe writes its counter under `$HOME/.astrolabe` |
+
+## The sandbox detail that matters
+
+DSH runs hook commands inside its file sandbox. The user's home is readable but
+**not writable** there, so Astrolabe's counter write to `~/.astrolabe/hook_data/`
+fails and the hook silently fails open — the guard appears to be installed but
+never denies anything.
+
+The plugin therefore points the hook process at a writable `HOME`
+(`stateDir`) instead of widening the sandbox. Counters live under
+`<tmpdir>/astrolabe-dsh-guard/.astrolabe/hook_data/<session_id>/counter.json`
+and reset when the OS clears the temp directory.
+
+## Behaviour
+
+- Tools observed: `grep`, `read`, `glob`, `bash`/`shell`, `rg`, plus every
+  Astrolabe MCP tool (so that using Astrolabe resets the counter).
+- Default threshold: the 3rd consecutive `grep`/`read` without an intervening
+  symbolic Astrolabe call is denied, with Astrolabe's own reason text forwarded
+  to the model.
+- Any failure (missing binary, timeout, unparsable output, sandbox fault) **fails
+  open**: the tool call proceeds.
+
+## Notes
+
+- Astrolabe identifies its own tools by substring, so DSH's per-repository server
+  names (`mcp__astrolabe-<repo>__find_symbol`) need no rewriting.
+- `search_code` is a *non-symbolic* Astrolabe tool: it does not reset the
+  grep/read counter (by Astrolabe's own design). Use `find_symbol` /
+  `resolve_context` / `find_references` / `goto_definition` to reset it.
+
+## Licence
+
+MIT OR Apache-2.0, matching the rest of Astrolabe.

package/lib/setup/vendor/astrolabe-dsh-guard/cordis.patch.yml

@@ -0,0 +1,11 @@
+# Bundle patch for DeepSeek Harness: inserts the Astrolabe drift guard plugin.
+#
+# Installed through the harness plugin manager (it declares `dsh.bundle`), or
+# copied into a profile and referenced from the profile's own cordis.patch.yml.
+# `astrolabe` must be on PATH for the plugin's `shell` calls; override the
+# binary path with `config.binary` when it is not.
+- insert:
+    - id: astrolabe-guard
+      name: 'astrolabe-dsh-guard'
+      config:
+        client: claude-code

package/lib/setup/vendor/astrolabe-dsh-guard/lib/index.js

@@ -0,0 +1,145 @@
+/**
+ * Astrolabe drift guard for DeepSeek Harness — native hook plugin.
+ *
+ * DeepSeek Harness has no hook config file of its own: a "native hook" is an
+ * ordinary Cordis plugin subscribing to the canonical interception events, and
+ * the `dsh-hooks-claude-code` / `dsh-hooks-codex` packages are only translators
+ * that map an external shell-hook protocol onto that same API. This plugin skips
+ * the translation: it runs `astrolabe hooks remind` on `tools/pre-execute` and
+ * maps the returned decision onto the harness's typed `PreToolDecision`.
+ *
+ * Astrolabe recognises its own MCP tools by substring, so a per-repository
+ * server name such as `mcp__astrolabe-dict__find_symbol` already resets the
+ * consecutive grep/read counter; no tool-name rewriting is needed here.
+ *
+ * @module astrolabe-dsh-guard
+ */
+
+import { mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+export const name = 'astrolabe-guard'
+
+/** The command runner, the same seam the hook bridges use. */
+export const inject = ['shell']
+
+/**
+ * Tools whose calls change Astrolabe's drift counter.
+ *
+ * `grep`, `read`, `glob` and shell text search accumulate the counter; every
+ * Astrolabe tool call must also reach the hook so the counter resets — a denied
+ * grep otherwise stays denied until the idle timeout. Unrelated tools are
+ * skipped to avoid one process spawn per tool call.
+ */
+const RELEVANT = /^(grep|read|glob|bash|shell|rg)$/i
+
+/** Astrolabe tool names as they appear after an MCP server prefix. */
+const ASTROLABE_TOOL =
+  /(?:^|__)(search_code|find_symbol|find_references|goto_definition|resolve_context|get_diagnostics|get_languages)$/
+
+/**
+ * Whether this call can change Astrolabe's drift counter.
+ * @param toolName - the harness tool name, e.g. `grep` or `mcp__astrolabe-dict__search_code`.
+ * @returns true when the hook must observe the call.
+ */
+function relevant(toolName) {
+  return RELEVANT.test(toolName) || (toolName.includes('astrolabe') && ASTROLABE_TOOL.test(toolName))
+}
+
+/**
+ * Build the `PreToolUse` payload `astrolabe hooks remind` parses.
+ * @param exec - the tool execution being gated.
+ * @returns the payload object.
+ */
+function payloadOf(exec) {
+  return {
+    session_id: exec.agent?.session?.header?.id ?? '',
+    transcript_path: '',
+    cwd: exec.agent?.session?.header?.cwd ?? process.cwd(),
+    hook_event_name: 'PreToolUse',
+    tool_name: exec.name,
+    tool_input: exec.arguments,
+    tool_use_id: exec.callId,
+  }
+}
+
+/**
+ * Run `astrolabe hooks remind` and decode its decision.
+ * @param shell - the harness shell executor.
+ * @param spec - binary, client dialect, timeout, state home and the payload to pipe in.
+ * @returns the decoded hook output, or undefined when it printed nothing usable.
+ */
+async function remind(shell, spec) {
+  const request = {
+    command: `${spec.binary} hooks remind --client=${spec.client}`,
+    timeoutMs: spec.timeoutMs,
+    stdin: JSON.stringify(spec.payload),
+    // Astrolabe persists its consecutive-call counter under `$HOME/.astrolabe`.
+    // This command runs inside the harness file sandbox, where the user's home
+    // is readable but not writable, so the counter write would fail and the hook
+    // would silently fail open. A writable state home keeps the counter alive
+    // without widening the sandbox.
+    env: { HOME: spec.stateHome },
+    ...(spec.signal === undefined ? {} : { signal: spec.signal }),
+  }
+  const result = await (await shell.execute(shell.resolve(request))).result()
+  const text = (result.stdout?.text ?? '').trim()
+  if (text === '') return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    // A malformed decision is not a blocking one: fail open.
+    return undefined
+  }
+}
+
+/**
+ * Install the guard.
+ * @param ctx - the plugin context, providing `shell` and the tool events.
+ * @param config - plugin configuration (all optional).
+ */
+export function apply(ctx, config = {}) {
+  const binary = typeof config.binary === 'string' && config.binary !== '' ? config.binary : 'astrolabe'
+  const client = typeof config.client === 'string' && config.client !== '' ? config.client : 'claude-code'
+  const timeoutMs = Number.isFinite(config.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : 20000
+  const stateHome = typeof config.stateDir === 'string' && config.stateDir !== ''
+    ? config.stateDir
+    : join(tmpdir(), 'astrolabe-dsh-guard')
+
+  try {
+    mkdirSync(stateHome, { recursive: true })
+  } catch {
+    // A state home we cannot create leaves the hook fail-open, never blocking.
+  }
+
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    if (!relevant(exec.name)) return next()
+
+    let output
+    try {
+      output = await remind(ctx.shell, {
+        binary,
+        client,
+        timeoutMs,
+        stateHome,
+        payload: payloadOf(exec),
+        signal: exec.signal,
+      })
+    } catch {
+      // A hook that cannot run must never block the turn — same rule as the
+      // harness's own hook bridges.
+      return next()
+    }
+
+    const decision = output?.hookSpecificOutput
+    if (decision?.permissionDecision === 'deny') {
+      return {
+        kind: 'deny',
+        reason: decision.permissionDecisionReason
+          ?? 'Astrolabe: use the MCP code-navigation tools instead of grep/read',
+      }
+    }
+    return next()
+  })
+}

package/lib/setup/vendor/astrolabe-dsh-guard/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "astrolabe-dsh-guard",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Astrolabe drift guard for DeepSeek Harness: deny repeated grep/read calls and steer the model to Astrolabe's MCP code-navigation tools.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "astrolabe",
+    "hook",
+    "mcp"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wojiushirencai/Astrolabe.git",
+    "directory": "dsh-plugin"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/lib/setup/zcode.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const REMIND_CMD = 'astrolabe hooks remind --client=zcode';
+
+function detectZCode(home, env, { whichFn, existsFn }) {
+  const evidence = [];
+  if (whichFn('zcode', env)) evidence.push('zcode on PATH');
+  if (existsFn(path.join(home, '.zcode'))) evidence.push('~/.zcode/');
+  if (existsFn(path.join(home, '.zcode', 'cli'))) evidence.push('~/.zcode/cli/');
+  if (existsFn(path.join(home, '.zcode', 'cli', 'config.json'))) {
+    evidence.push('~/.zcode/cli/config.json');
+  }
+  return { detected: evidence.length > 0, evidence };
+}
+
+function resolveZcodeConfigPath(home, existsFn) {
+  // Prefer documented ~/.zcode/cli/config.json (HOOKS.md + z.ai docs).
+  // Some forks also use setting.json; only fall back when that alone exists.
+  const configJson = path.join(home, '.zcode', 'cli', 'config.json');
+  const settingJson = path.join(home, '.zcode', 'cli', 'setting.json');
+  if (existsFn(configJson)) return configJson;
+  if (existsFn(settingJson)) return settingJson;
+  return configJson;
+}
+
+function zcodeServerEntry(launch) {
+  return {
+    type: 'stdio',
+    command: launch.command,
+    args: launch.args,
+  };
+}
+
+function preToolUseEntry() {
+  return {
+    matcher: '*',
+    hooks: [
+      {
+        type: 'command',
+        command: REMIND_CMD,
+        timeout: 10,
+      },
+    ],
+  };
+}
+
+function entryHasRemind(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+  return hooks.some(
+    (h) =>
+      h &&
+      typeof h.command === 'string' &&
+      h.command.includes('astrolabe hooks remind --client=zcode'),
+  );
+}
+
+/**
+ * Merge mcp.servers.astrolabe and (optional) hooks.events.PreToolUse into
+ * ~/.zcode/cli/config.json. Never writes SessionEnd; never hangs cleanup on Stop.
+ */
+function mergeZcodeConfigFile(
+  filePath,
+  launch,
+  { create = true, withHooks = false, existsFn = fs.existsSync } = {},
+) {
+  let created = false;
+  let doc = {};
+  if (existsFn(filePath)) {
+    const raw = fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '');
+    doc = JSON.parse(raw);
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+      throw new Error(`${filePath} root must be a JSON object`);
+    }
+  } else if (!create) {
+    return { skipped: true, reason: `missing ${filePath} (will not create)` };
+  } else {
+    created = true;
+  }
+
+  if (!doc.mcp || typeof doc.mcp !== 'object' || Array.isArray(doc.mcp)) {
+    doc.mcp = {};
+  }
+  if (!doc.mcp.servers || typeof doc.mcp.servers !== 'object' || Array.isArray(doc.mcp.servers)) {
+    doc.mcp.servers = {};
+  }
+  const hadServer = Object.prototype.hasOwnProperty.call(doc.mcp.servers, 'astrolabe');
+  doc.mcp.servers.astrolabe = zcodeServerEntry(launch);
+
+  let hooksReplaced = false;
+  if (withHooks) {
+    if (!doc.hooks || typeof doc.hooks !== 'object' || Array.isArray(doc.hooks)) {
+      doc.hooks = {};
+    }
+    doc.hooks.enabled = true;
+    if (!doc.hooks.events || typeof doc.hooks.events !== 'object' || Array.isArray(doc.hooks.events)) {
+      doc.hooks.events = {};
+    }
+    // Hard rule: never SessionEnd (ZCode rejects unknown events).
+    if (Object.prototype.hasOwnProperty.call(doc.hooks.events, 'SessionEnd')) {
+      delete doc.hooks.events.SessionEnd;
+    }
+    if (!Array.isArray(doc.hooks.events.PreToolUse)) {
+      doc.hooks.events.PreToolUse = [];
+    }
+    const idx = doc.hooks.events.PreToolUse.findIndex(entryHasRemind);
+    const next = preToolUseEntry();
+    if (idx >= 0) {
+      doc.hooks.events.PreToolUse[idx] = next;
+      hooksReplaced = true;
+    } else {
+      doc.hooks.events.PreToolUse.push(next);
+    }
+  }
+
+  return {
+    filePath,
+    doc,
+    created,
+    replaced: hadServer || hooksReplaced,
+    entry: doc.mcp.servers.astrolabe,
+    withHooks,
+  };
+}
+
+module.exports = {
+  REMIND_CMD,
+  detectZCode,
+  resolveZcodeConfigPath,
+  zcodeServerEntry,
+  mergeZcodeConfigFile,
+};