@lifenrir/dsh-external-task-context-patch 0.0.0-stage → 0.1.0

package/lib.mjs

@@ -0,0 +1,274 @@
+/**
+ * Helper functions for the patch installer: argument parsing, version/tag
+ * mapping, DSH home resolution, profile discovery, and install-record checks.
+ * These helpers are free of installer side effects so they can be unit tested.
+ *
+ * @module dsh-external-task-context-patch/lib
+ */
+
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+/** npm name of the provider package this patch targets. */
+export const PROVIDER_PACKAGE_NAME = '@deepseek-ai/dsh-subagent-claude-code'
+
+/** git tag used when the caller does not pass `--tag`. */
+export const DEFAULT_TAG = 'dsh-v0.2.2-rc.1'
+
+/** Official provider source files fetched or read from `--source`. */
+export const PROVIDER_SRC_FILES = ['index.ts', 'run.ts', 'process.ts']
+
+/** Patched source files copied from this package's `src/` directory. */
+export const PATCHED_SRC_FILES = ['index.ts', 'run.ts', 'log.ts']
+
+/** Directory name under `<DSH_HOME>/backups` that owns all patch records. */
+export const BACKUP_DIR_NAME = 'subagent-claude-code-patch'
+
+/** Relative path of the run-log directory created by the patched provider. */
+export const RUN_LOG_RELATIVE_PATH = ['logs', 'subagent-claude-code']
+
+const VALUE_OPTIONS = new Set(['--dsh-home', '--profile', '--tag', '--source'])
+const FLAG_OPTIONS = new Set(['--dry-run', '--force', '--restore', '--yes', '--help', '-h'])
+
+/**
+ * Parse installer CLI arguments.
+ * @param {readonly string[]} argv - process arguments without the executable and script.
+ * @returns {{ dshHome: string | undefined, profiles: string[], tag: string, source: string | undefined, dryRun: boolean, force: boolean, restore: boolean, yes: boolean, help: boolean }}
+ * @throws {Error} on an unknown option, a missing value, or an invalid profile name.
+ */
+export function parseArgs(argv) {
+  const options = {
+    dshHome: undefined,
+    profiles: [],
+    tag: DEFAULT_TAG,
+    source: undefined,
+    dryRun: false,
+    force: false,
+    restore: false,
+    yes: false,
+    help: false,
+  }
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]
+    if (FLAG_OPTIONS.has(argument)) {
+      switch (argument) {
+        case '--dry-run': options.dryRun = true; break
+        case '--force': options.force = true; break
+        case '--restore': options.restore = true; break
+        case '--yes': options.yes = true; break
+        default: options.help = true
+      }
+      continue
+    }
+
+    let name = argument
+    let value
+    const equals = argument.indexOf('=')
+    if (argument.startsWith('--') && equals !== -1) {
+      name = argument.slice(0, equals)
+      value = argument.slice(equals + 1)
+    }
+    if (!VALUE_OPTIONS.has(name)) {
+      throw new Error(`unknown option: ${argument}`)
+    }
+    if (value === undefined) {
+      index += 1
+      value = argv[index]
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error(`missing value for ${name}`)
+      }
+    }
+    if (value.trim().length === 0) {
+      throw new Error(`empty value for ${name}`)
+    }
+    switch (name) {
+      case '--dsh-home': options.dshHome = value; break
+      case '--profile': options.profiles.push(assertProfileName(value)); break
+      case '--tag': options.tag = value; break
+      case '--source': options.source = value; break
+      default: throw new Error(`unknown option: ${name}`)
+    }
+  }
+  return options
+}
+
+/**
+ * Reject profile names that could escape `<DSH_HOME>/profiles`.
+ * @param {string} name - profile directory name.
+ * @returns {string} the unchanged name when valid.
+ */
+export function assertProfileName(name) {
+  if (
+    name.length === 0
+    || name === '.'
+    || name === '..'
+    || name.includes('/')
+    || name.includes('\\')
+  ) {
+    throw new Error(`invalid profile name: ${name}`)
+  }
+  return name
+}
+
+/**
+ * Resolve the DeepSeek Harness home directory.
+ * @param {string | undefined} explicit - `--dsh-home` value, when supplied.
+ * @param {NodeJS.ProcessEnv} [env] - environment source.
+ * @param {string} [home] - operating-system home directory.
+ * @returns {string} absolute DSH home path.
+ * @throws {Error} when an explicit `--dsh-home` is blank.
+ */
+export function resolveDshHome(explicit, env = process.env, home = homedir()) {
+  if (explicit !== undefined) {
+    if (explicit.trim().length === 0) {
+      throw new Error('--dsh-home must not be empty')
+    }
+    return resolve(explicit.trim())
+  }
+  const configured = env.DSH_HOME
+  if (configured !== undefined && configured.trim().length > 0) {
+    return resolve(configured.trim())
+  }
+  return join(home, '.dsh')
+}
+
+/**
+ * Map a provider package version to its deepseek-harness git tag.
+ * @param {string} version - package version, for example `0.2.2-rc.1`.
+ * @returns {string} tag, for example `dsh-v0.2.2-rc.1`.
+ */
+export function versionToTag(version) {
+  if (typeof version !== 'string' || version.trim().length === 0) {
+    throw new Error('provider version is empty')
+  }
+  return `dsh-v${version.trim()}`
+}
+
+/**
+ * Map a deepseek-harness git tag to the provider package version.
+ * @param {string} tag - tag, for example `dsh-v0.2.2-rc.1`.
+ * @returns {string} version, for example `0.2.2-rc.1`.
+ */
+export function tagToVersion(tag) {
+  if (typeof tag !== 'string' || !tag.startsWith('dsh-v') || tag.length === 5) {
+    throw new Error(`invalid DSH release tag: ${String(tag)}`)
+  }
+  return tag.slice(5)
+}
+
+/**
+ * Whether an installed provider version matches the requested tag.
+ * @param {string} version - installed package version.
+ * @param {string} tag - requested git tag.
+ * @returns {boolean} true when both name the same release.
+ */
+export function versionMatchesTag(version, tag) {
+  return version === tagToVersion(tag)
+}
+
+/**
+ * Directory holding one profile's installed provider package.
+ * @param {string} profileDir - absolute profile directory.
+ * @returns {string} absolute provider package directory.
+ */
+export function providerDirFor(profileDir) {
+  return join(profileDir, 'node_modules', ...PROVIDER_PACKAGE_NAME.split('/'))
+}
+
+/**
+ * List profiles that have the target provider installed.
+ * @param {string} dshHome - absolute DSH home.
+ * @param {{ readdir?: typeof readdir, exists?: (path: string) => boolean }} [io] - injection points for tests.
+ * @returns {Promise<string[]>} matching profile names, sorted.
+ */
+export async function discoverProfiles(dshHome, io = {}) {
+  const readdirImpl = io.readdir ?? readdir
+  const existsImpl = io.exists ?? existsSync
+  const profilesRoot = join(dshHome, 'profiles')
+  let entries
+  try {
+    entries = await readdirImpl(profilesRoot, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const matches = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+    if (existsImpl(providerDirFor(join(profilesRoot, entry.name)))) {
+      matches.push(entry.name)
+    }
+  }
+  return matches.sort()
+}
+
+/**
+ * Render a filesystem-safe UTC timestamp used as a backup directory name.
+ * @param {Date} [date] - instant to render.
+ * @returns {string} timestamp such as `2026-11-06T14-07-00-000Z`.
+ */
+export function timestampDir(date = new Date()) {
+  return date.toISOString().replace(/[:.]/g, '-')
+}
+
+/**
+ * Build the GitHub raw URL for one official provider source file.
+ * @param {string} tag - release tag.
+ * @param {string} file - source file name.
+ * @returns {string} raw.githubusercontent.com URL.
+ */
+export function rawSourceUrl(tag, file) {
+  const path = [
+    'deepseek-ai',
+    'deepseek-harness',
+    tag,
+    'packages',
+    'subagent',
+    'subagent-claude-code',
+    'src',
+    file,
+  ].map(part => encodeURIComponent(part)).join('/')
+  return `https://raw.githubusercontent.com/${path}`
+}
+
+/**
+ * Root directory that owns timestamped backup sets.
+ * @param {string} dshHome - absolute DSH home.
+ * @returns {string} absolute backup root.
+ */
+export function backupsRoot(dshHome) {
+  return join(dshHome, 'backups', BACKUP_DIR_NAME)
+}
+
+/**
+ * Backup directory for one profile inside a timestamped set.
+ * @param {string} dshHome - absolute DSH home.
+ * @param {string} timestamp - output of {@link timestampDir}.
+ * @param {string} profile - profile name.
+ * @returns {string} absolute backup directory.
+ */
+export function backupProfileDir(dshHome, timestamp, profile) {
+  return join(backupsRoot(dshHome), timestamp, assertProfileName(profile))
+}
+
+/**
+ * Run-log directory reported by the patched provider.
+ * @param {string} dshHome - absolute DSH home.
+ * @returns {string} absolute log directory.
+ */
+export function runLogDirectory(dshHome) {
+  return join(dshHome, ...RUN_LOG_RELATIVE_PATH)
+}
+
+/**
+ * Whether an install record represents an active patch for the given tag.
+ * @param {{ tag?: string, restoredAt?: string } | undefined} record - install record.
+ * @param {string} tag - requested tag.
+ * @returns {boolean} true when the record is unrestored and names the same tag.
+ */
+export function isMatchingActiveRecord(record, tag) {
+  return record !== undefined
+    && record.tag === tag
+    && (record.restoredAt === undefined || record.restoredAt === null)
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@lifenrir/dsh-external-task-context-patch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Install a run-log-capable patched @deepseek-ai/dsh-subagent-claude-code into an existing DSH profile for @lifenrir/dsh-external-task-context live logs.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "dsh-external-task-context-patch": "./install.mjs"
+  },
+  "files": [
+    "install.mjs",
+    "lib.mjs",
+    "src",
+    "README.md",
+    "README-zh.md"
+  ],
+  "dependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "scripts": {
+    "test": "node --test tests/lib.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LiFenrir/dsh-external-task-context.git",
+    "directory": "patch"
+  },
+  "homepage": "https://github.com/LiFenrir/dsh-external-task-context/tree/main/patch#readme",
+  "bugs": {
+    "url": "https://github.com/LiFenrir/dsh-external-task-context/issues"
+  }
+}

package/src/index.ts

@@ -0,0 +1,189 @@
+/**
+ * Profile-named Claude Code one-shot subagent provider. Every accepted run
+ * invokes the official Agent SDK in the delegating Session's workspace and
+ * places the SDK-spawned real CLI under the shared subprocess owner.
+ *
+ * @module @deepseek-ai/dsh-subagent-claude-code
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import {
+  assertPositiveFinite,
+  NO_START_CAPABILITIES,
+  assertUsableCwd,
+  type ResolvedSubagentStartRequest,
+  type SubagentCapabilities,
+  type SubagentProvider,
+} from '@deepseek-ai/dsh-subagent'
+import { DEFAULT_LOG_RETENTION_DAYS } from './log.ts'
+import {
+  CLAUDE_CODE_PERMISSION_MODES,
+  DEFAULT_CLAUDE_CODE_PERMISSION_MODE,
+  DEFAULT_DISPOSE_GRACE_MS,
+  claudeCodeStartupFailure,
+  startClaudeCodeRun,
+  type ClaudeCodePermissionMode,
+  type ClaudeCodeRunSpec,
+} from './run.ts'
+
+export const name = 'subagent-claude-code'
+export const inject = ['subagents', 'subprocess']
+
+const DEFAULT_PROVIDER_NAME = 'claude-code'
+
+/* jscpd:ignore-start -- sibling product providers intentionally expose
+ * overlapping deployment-owned fields without adding a shared config owner. */
+/** Deployment-owned model, permission, environment, and process-release settings. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `claude-code`). */
+  providerName?: string
+  /** Native Claude model fixed for this instance; omitted to inherit Claude settings. */
+  model?: string
+  /**
+   * Explicit environment entries layered over the subprocess seam's
+   * credential-scrubbed parent environment.
+   */
+  env?: Record<string, string>
+  /**
+   * Native non-interactive mode fixed for this Provider instance. Defaults to
+   * `dontAsk`; `acceptEdits` accepts edits, `auto` uses the native classifier,
+   * `plan` returns a plan without approving execution, and
+   * `bypassPermissions` explicitly skips permission checks.
+   */
+  permissionMode?: ClaudeCodePermissionMode
+  /** Grace in milliseconds between Claude Code managed-range termination tiers. */
+  disposeGraceMs?: number
+  /**
+   * Directory for per-run JSONL and metadata logs. Defaults, resolved at run
+   * time, to `<DSH_HOME>/logs/subagent-claude-code`.
+   */
+  logDirectory?: string
+  /** Days to retain finished run logs (default 7; must be a positive finite number). */
+  logRetentionDays?: number
+  /**
+   * Whether Claude Code persists its native session transcript, which the SDK
+   * writes under `<CLAUDE_CONFIG_DIR>/projects/<cwd>/<sessionId>.jsonl`
+   * (default true).
+   */
+  persistNativeTranscript?: boolean
+  /** Whether the SDK streams partial assistant messages so deltas reach the log (default true). */
+  includePartialMessages?: boolean
+}
+
+export const Config: z<Config> = z.object({
+  providerName: z.string().min(1).default(DEFAULT_PROVIDER_NAME),
+  model: z.string().min(1),
+  env: z.dict(z.string()).default({}),
+  permissionMode: z.union([...CLAUDE_CODE_PERMISSION_MODES])
+    .default(DEFAULT_CLAUDE_CODE_PERMISSION_MODE),
+  disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS),
+  logDirectory: z.string().min(1),
+  logRetentionDays: z.number().default(DEFAULT_LOG_RETENTION_DAYS),
+  persistNativeTranscript: z.boolean().default(true),
+  includePartialMessages: z.boolean().default(true),
+})
+
+type ResolvedConfig = Omit<Required<Config>, 'model' | 'logDirectory'>
+  & Pick<Config, 'model' | 'logDirectory'>
+/* jscpd:ignore-end */
+
+/* jscpd:ignore-start -- Cordis registration and shared-seam plumbing mirror
+ * the Codex sibling; each product's lifecycle remains package-private. */
+class ClaudeCodeProvider implements SubagentProvider {
+  readonly capabilities: SubagentCapabilities = NO_START_CAPABILITIES
+  readonly inheritsParentContext = false
+
+  constructor(
+    readonly name: string,
+    private readonly ctx: Context,
+    private readonly config: ResolvedConfig,
+  ) {}
+
+  async start(request: ResolvedSubagentStartRequest) {
+    let cwd: string
+    try {
+      cwd = assertUsableCwd('subagent-claude-code', 'child cwd', request.cwd)
+    } catch (error: unknown) {
+      if (request.signal.aborted) {
+        throw new Error(
+          'subagent-claude-code: request was aborted before SDK startup',
+        )
+      }
+      const failure = claudeCodeStartupFailure(error)
+      this.ctx.logger.warn(
+        `subagent-claude-code "${this.name}": child start failed: %o`,
+        failure,
+      )
+      throw failure
+    }
+    const spec: ClaudeCodeRunSpec = {
+      cwd,
+      ...this.config.model === undefined ? {} : { model: this.config.model },
+      permissionMode: this.config.permissionMode,
+      env: this.config.env,
+      disposeGraceMs: this.config.disposeGraceMs,
+      ...this.config.logDirectory === undefined
+        ? {}
+        : { logDirectory: this.config.logDirectory },
+      logRetentionDays: this.config.logRetentionDays,
+      persistNativeTranscript: this.config.persistNativeTranscript,
+      includePartialMessages: this.config.includePartialMessages,
+      spawn: spawnSpec => this.ctx.subprocess.spawn(spawnSpec),
+      onError: (error, stopReason) => {
+        this.ctx.logger.warn(
+          `subagent-claude-code "${this.name}": child run failed (${stopReason}): %o`,
+          error,
+        )
+      },
+      onLogError: (error) => {
+        this.ctx.logger.warn(
+          `subagent-claude-code "${this.name}": run log write failed: %o`,
+          error,
+        )
+      },
+    }
+    return startClaudeCodeRun(request, spec)
+  }
+}
+
+/**
+ * Register one Profile-named Claude Code provider.
+ * @param ctx - context carrying shared subagent and subprocess services.
+ * @param config - registry name, optional model, permission mode, child environment, disposal grace, and run-log policy.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const resolved: ResolvedConfig = {
+    providerName: config.providerName ?? DEFAULT_PROVIDER_NAME,
+    ...config.model === undefined ? {} : { model: config.model },
+    env: config.env as Record<string, string>,
+    permissionMode: config.permissionMode ?? DEFAULT_CLAUDE_CODE_PERMISSION_MODE,
+    disposeGraceMs: config.disposeGraceMs as number,
+    logRetentionDays: config.logRetentionDays ?? DEFAULT_LOG_RETENTION_DAYS,
+    persistNativeTranscript: config.persistNativeTranscript ?? true,
+    includePartialMessages: config.includePartialMessages ?? true,
+    ...config.logDirectory === undefined ? {} : { logDirectory: config.logDirectory },
+  }
+  assertPositiveFinite(
+    'subagent-claude-code',
+    'disposeGraceMs',
+    resolved.disposeGraceMs,
+  )
+  if (resolved.disposeGraceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(
+      `subagent-claude-code: disposeGraceMs must be no greater than ${MAX_TIMER_DELAY_MS}`,
+    )
+  }
+  assertPositiveFinite(
+    'subagent-claude-code',
+    'logRetentionDays',
+    resolved.logRetentionDays,
+  )
+  ctx.subagents.registerProvider(new ClaudeCodeProvider(
+    resolved.providerName,
+    ctx,
+    resolved,
+  ))
+}
+/* jscpd:ignore-end */