s-app-scoder-agent 0.6.0 → 0.7.0

package/dist/prompt.js

@@ -0,0 +1,97 @@
+/**
+ * System prompt của Scoder — tách thành module riêng để:
+ *  - versioning rõ ràng (PROMPT_VERSION được ghi vào session JSONL khi chạy),
+ *  - test được độc lập (không cần instantiate Agent).
+ *
+ * V3 — stricter scope rules, clarification-before-action, safety boundaries,
+ * MCP/skills as passive listings only:
+ *  - ORIENT: read relevant files before ANY edit
+ *  - PLAN: specific and actionable, not generic
+ *  - EDIT: match existing style, minimal diffs
+ *  - VERIFY: read the FULL error, fix the cause not the symptom
+ *  - Safety & Boundaries: explicit prohibitions on git hooks, CI configs,
+ *    dependencies, infrastructure configs, and destructive commands
+ *  - Tool selection: concrete descriptions with explicit usage rules
+ *  - Skills/MCP: passive listing, never auto-load
+ */
+export const PROMPT_VERSION = 3;
+export const SYSTEM_PROMPT = `You are Scoder, an autonomous coding agent running in a terminal.
+You complete coding tasks end-to-end: exploring the code, editing files, and
+verifying your work with the build command. You act; you don't just advise.
+
+## How you work
+
+1. ORIENT: Before touching ANY code, read the relevant files using
+   \`list_files\` and \`read_file\`. Never edit a file you haven't read.
+2. PLAN: For any multi-step task, call \`write_todos\` with the full plan BEFORE
+   editing. Plans must be specific and actionable — not generic. Keep it live:
+   mark each item completed IMMEDIATELY after it is done (exactly one in_progress
+   at a time) and add newly discovered steps.
+3. EDIT: Make small, focused changes. Match the file's existing style
+   (indentation, quote style, naming conventions) — do NOT reformat unrelated
+   parts. Never refactor unrelated code, never add speculative features.
+4. VERIFY: Read the FULL error output before editing — fix the CAUSE, not the
+   symptom. Errors can be misleading (e.g. 'X not found' might be caused by a
+   missing import upstream). Then run the build command.
+5. REPORT: Your final message states what changed, why, and anything left
+   unresolved. Be honest: if something didn't work, say exactly what failed.
+
+## Tool selection
+
+- **read_file**: Read file content WITH LINE NUMBERS. Use when you need to see
+  actual code to edit. Always use for any file before edit_file.
+- **list_files**: List directory contents. Use to inspect project structure.
+- **edit_file**: Targeted string replacement. old_string MUST appear EXACTLY once —
+  if not found, read the file again and verify your text.
+- **write_file**: Create or overwrite. Parent dirs created automatically. Use for
+  new files or when write is cleaner than targeted edits.
+- **run_command**: Run shell command. Captures stdout + stderr. THIS IS THE BUILD
+  COMMAND — every task ends with run_command(<buildCmd>).
+- **write_todos**: Plan + live progress for multi-step work.
+- **web_fetch**: Exact URLs only (it cannot search). Use for library/API docs,
+  versions, changelogs when the answer isn't in the working directory.
+- **load_skill**: Only when the user explicitly requests it with "/skill <name>",
+  or when the task clearly matches a skill domain — do NOT load skills automatically.
+- **MCP tools (mcp__<server>__<tool>)**: Only when the task explicitly requires
+  external integration — never call MCP tools just because they exist.
+
+## Safety & Boundaries
+
+- **NEVER** modify git hooks, CI configs, package.json scripts, or any automated
+  tooling unless explicitly asked.
+- **NEVER** add new dependencies without explicit user approval.
+- **NEVER** touch production infrastructure configs (nginx, docker-compose,
+  kubernetes, etc.) unless the task is about them.
+- **NEVER** run destructive commands (rm -rf, --force, --rebase, etc.) without
+  explaining the risk to the user first.
+
+## Scope & Clarification
+
+1. Work within the EXACT scope of the request. Do NOT:
+   - Fix unrelated bugs you discover
+   - Refactor or reformat unrelated code
+   - Add features not asked for
+   - Improve code quality outside the task scope
+2. If the request is ambiguous or the scope is unclear: ask ONE clarifying question
+   before taking action. Do NOT guess and proceed — clarify first.
+3. When you believe the task is done, call run_command with the build command.
+   The loop ends only when the build succeeds.
+4. If run_command is denied by permission policy, find a safer alternative or
+   report the limitation clearly. Do not retry the same denied command.
+5. If an environmental problem makes the task impossible, stop and report it.
+
+## Quality bar
+
+- Reproduce a bug before fixing it (run the failing command, read the output).
+- Prefer the smallest change that makes the build pass.
+- Leave the code as you found it outside the scope of the task: no stray
+  debug prints, no leftover TODOs, no reformatting.
+- If you add code, add only what's needed now; note follow-ups in your final
+  message instead of implementing them.`;
+/** Ghép phần động (workdir/build/env/skills/MCP) vào system prompt gốc. */
+export function buildSystemPrompt(parts) {
+    return (SYSTEM_PROMPT +
+        `\n\nWorking directory: ${parts.workdir}\nBuild command (stop condition): ${parts.buildCmd}\n${parts.envInfo}` +
+        parts.skillsBlock +
+        parts.mcpBlock);
+}

package/dist/provider-anthropic.js

@@ -1,4 +1,4 @@
-import { LlmError, LLM_REQUEST_TIMEOUT_MS, combinedSignal } from "./llm.js";
+import { LlmError, LLM_REQUEST_TIMEOUT_MS, combinedSignal, redactSecrets } from "./llm.js";
 import { withRetry } from "./retry.js";
 // ---------------------------------------------------------------------------
 // Translation: OpenAI-style -> Anthropic
@@ -59,11 +59,15 @@ export function toAnthropicMessages(messages) {
 // ---------------------------------------------------------------------------
 export function fromAnthropicResponse(data) {
     let text = "";
+    let thinking = "";
     const toolCalls = [];
     for (const block of data.content ?? []) {
         if (block.type === "text") {
             text = text ? `${text}\n${block.text ?? ""}` : (block.text ?? "");
         }
+        else if (block.type === "thinking") {
+            thinking += block.thinking ?? "";
+        }
         else if (block.type === "tool_use") {
             toolCalls.push({
                 id: block.id ?? "",
@@ -83,6 +87,7 @@ export function fromAnthropicResponse(data) {
         message: {
             role: "assistant",
             content: text.length > 0 ? text : null,
+            reasoning: thinking || undefined,
             tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
         },
         usage,
@@ -94,30 +99,80 @@ export function fromAnthropicResponse(data) {
 const ANTHROPIC_VERSION = "2023-06-01";
 export class AnthropicClient {
     opts;
+    /** Last interrupted stream's accumulated tool calls (H-09 continuation). */
+    lastPartialToolCalls = [];
     constructor(opts) {
         this.opts = opts;
     }
+    get timeoutMs() {
+        return this.opts.requestTimeoutMs ?? LLM_REQUEST_TIMEOUT_MS;
+    }
+    /**
+     * I-04 prompt caching — Anthropic 4-block formula (≤4 cache breakpoints):
+     * tools (last block), system, and the last user message get
+     * `cache_control: {type: "ephemeral"}`. Applied only when enableCache.
+     */
+    applyCacheControl(system, translated, tools) {
+        if (!this.opts.enableCache)
+            return { system, messages: translated, tools };
+        const CC = { cache_control: { type: "ephemeral" } };
+        // System: string → single block array with marker.
+        const sysOut = system
+            ? [{ type: "text", text: system, ...CC }]
+            : undefined;
+        // Tools: last definition carries the marker.
+        const toolsOut = tools && tools.length > 0
+            ? tools.map((t, i) => ({
+                name: t.function.name,
+                description: t.function.description,
+                input_schema: t.function.parameters,
+                ...(i === tools.length - 1 ? CC : {}),
+            }))
+            : undefined;
+        // Last user message: annotate final content block (string → block array).
+        const messages = [...translated];
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === "user") {
+                const c = messages[i].content;
+                if (typeof c === "string") {
+                    messages[i] = { ...messages[i], content: [{ type: "text", text: c, ...CC }] };
+                }
+                else if (c.length > 0) {
+                    messages[i] = { ...messages[i], content: [...c.slice(0, -1), { ...c[c.length - 1], ...CC }] };
+                }
+                break;
+            }
+        }
+        return { system: sysOut, messages, tools: toolsOut };
+    }
     get model() {
         return this.opts.model;
     }
-    async chat(messages, tools, opts = {}) {
-        const url = `${this.opts.baseUrl.replace(/\/$/, "")}/messages`;
-        const { system, messages: translated } = toAnthropicMessages(messages);
-        const { signal, cleanup } = combinedSignal(opts.signal, LLM_REQUEST_TIMEOUT_MS);
-        const body = JSON.stringify({
+    /** T-04: runtime hot-swap — next request uses the new model id. */
+    setModel(model) {
+        this.opts = { ...this.opts, model };
+    }
+    /** I-05: request body builder — shared by chat/streamChat. */
+    buildBody(system, messages, tools, stream) {
+        // Extended thinking: temperature must be 1 và thinking block format.
+        const thinkingOn = (this.opts.thinkingBudgetTokens ?? 0) > 0;
+        return JSON.stringify({
             model: this.opts.model,
             max_tokens: this.opts.maxTokens,
-            temperature: this.opts.temperature,
+            temperature: thinkingOn ? 1 : this.opts.temperature,
+            ...(thinkingOn ? { thinking: { type: "enabled", budget_tokens: this.opts.thinkingBudgetTokens } } : {}),
             system,
-            messages: translated,
-            tools: tools.length > 0
-                ? tools.map((t) => ({
-                    name: t.function.name,
-                    description: t.function.description,
-                    input_schema: t.function.parameters,
-                }))
-                : undefined,
+            messages,
+            stream,
+            tools,
         });
+    }
+    async chat(messages, tools, opts = {}) {
+        const url = `${this.opts.baseUrl.replace(/\/$/, "")}/messages`;
+        const { system, messages: translated } = toAnthropicMessages(messages);
+        const { signal, cleanup } = combinedSignal(opts.signal, this.timeoutMs);
+        const cached = this.applyCacheControl(system, translated, tools);
+        const body = this.buildBody(cached.system, cached.messages, cached.tools, false);
         let res;
         try {
             res = await withRetry(async () => {
@@ -155,22 +210,9 @@ export class AnthropicClient {
     async *streamChat(messages, tools, opts = {}) {
         const url = `${this.opts.baseUrl.replace(/\/$/, "")}/messages`;
         const { system, messages: translated } = toAnthropicMessages(messages);
-        const { signal, cleanup } = combinedSignal(opts.signal, LLM_REQUEST_TIMEOUT_MS);
-        const body = JSON.stringify({
-            model: this.opts.model,
-            max_tokens: this.opts.maxTokens,
-            temperature: this.opts.temperature,
-            system,
-            messages: translated,
-            stream: true,
-            tools: tools.length > 0
-                ? tools.map((t) => ({
-                    name: t.function.name,
-                    description: t.function.description,
-                    input_schema: t.function.parameters,
-                }))
-                : undefined,
-        });
+        const { signal, cleanup, stopTimer } = combinedSignal(opts.signal, this.timeoutMs);
+        const cached = this.applyCacheControl(system, translated, tools);
+        const body = this.buildBody(cached.system, cached.messages, cached.tools, true);
         let res;
         try {
             res = await withRetry(async () => {
@@ -198,6 +240,7 @@ export class AnthropicClient {
         }
         // Accumulators — text content + tool_use blocks (by block index)
         let text = "";
+        let thinkingAccum = "";
         const toolBlocks = new Map();
         let stopReason;
         let usage;
@@ -205,6 +248,23 @@ export class AnthropicClient {
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
         let buffer = "";
+        // Headers received — switch whole-request timeout to idle timeout per read
+        // (same rationale as LlmClient.streamChat: long streams are normal).
+        stopTimer();
+        const idleTimeoutMs = opts.idleTimeoutMs ?? this.timeoutMs;
+        const readWithIdleTimeout = async () => {
+            const ac = new AbortController();
+            const t = setTimeout(() => ac.abort(new DOMException(`stream idle for ${idleTimeoutMs / 1000}s`, "TimeoutError")), idleTimeoutMs);
+            try {
+                return await Promise.race([
+                    reader.read(),
+                    new Promise((_, rej) => ac.signal.addEventListener("abort", () => rej(ac.signal.reason), { once: true })),
+                ]);
+            }
+            finally {
+                clearTimeout(t);
+            }
+        };
         const handleEvent = (raw) => {
             let ev;
             try {
@@ -239,6 +299,12 @@ export class AnthropicClient {
                     text += ev.delta.text;
                     return { contentDelta: ev.delta.text, done: false };
                 }
+                // I-05: thinking deltas stream as their own content block type.
+                if (ev.delta?.type === "thinking_delta" && ev.delta.thinking) {
+                    const t = ev.delta.thinking ?? "";
+                    thinkingAccum += t;
+                    return { reasoningDelta: t, done: false };
+                }
                 if (ev.delta?.type === "input_json_delta" && ev.delta.partial_json) {
                     const block = toolBlocks.get(ev.index ?? 0);
                     if (block)
@@ -272,9 +338,11 @@ export class AnthropicClient {
             return null;
         };
         let finalResult;
+        // Reset the partial-call record for this stream (H-09 continuation).
+        this.lastPartialToolCalls = [];
         try {
             while (true) {
-                const { done, value } = await reader.read();
+                const { done, value } = await readWithIdleTimeout();
                 if (done)
                     break;
                 buffer += decoder.decode(value, { stream: true });
@@ -300,6 +368,7 @@ export class AnthropicClient {
                     message: {
                         role: "assistant",
                         content: text.length > 0 ? text : null,
+                        reasoning: thinkingAccum || undefined,
                         stop_reason: stopReason,
                         tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
                     },
@@ -308,11 +377,20 @@ export class AnthropicClient {
             }
         }
         finally {
+            // H-09: record complete tool calls accumulated so far, for continuation.
+            this.lastPartialToolCalls = [...toolBlocks.values()]
+                .filter((b) => b.name)
+                .map((b) => ({ id: b.id, name: b.name, arguments: b.json || "{}" }));
             try {
-                reader.cancel();
+                const c = reader.cancel();
+                if (c && typeof c.catch === "function")
+                    c.catch(() => { });
             }
             catch { /* already released */ }
-            reader.releaseLock();
+            try {
+                reader.releaseLock();
+            }
+            catch { /* lock already released */ }
             cleanup();
         }
         yield { done: true, final: finalResult };
@@ -320,7 +398,7 @@ export class AnthropicClient {
 }
 async function toAnthropicError(res, url) {
     let body = await res.text().catch(() => "");
-    body = body.replace(/sk-ant-[^\s,&\]]+/gi, "sk-ant-***REDACTED***");
+    body = redactSecrets(body);
     const err = new LlmError(`Anthropic API error ${res.status} at ${url}: ${body.slice(0, 500)}`, res.status);
     const retryAfterHeader = res.headers.get("retry-after");
     if (retryAfterHeader != null && retryAfterHeader !== "") {

package/dist/provider-registry.js

@@ -0,0 +1,116 @@
+/**
+ * Provider Registry v2 (I-01) — unified runtime selection.
+ *
+ * Source: anomalyco/opencode (packages/core/src/provider.ts) — concept
+ * adapted: registry resolving a provider id → client runtime, from
+ * config `providers.<id>` entries + built-ins. No npm plugins in v1.0.
+ *
+ * Built-ins:
+ *   openai            — OpenAI chat-completions (default)
+ *   anthropic         — native Messages API (prompt caching, thinking)
+ *   openai-compatible — any OpenAI-compatible endpoint (DeepSeek, Groq, Together…)
+ *   ollama            — local Ollama (http://localhost:11434/v1)
+ *   gemini            — Gemini via its OpenAI-compat endpoint
+ */
+import { LlmClient } from "./llm.js";
+import { AnthropicClient } from "./provider-anthropic.js";
+export const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434/v1";
+export const DEFAULT_GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai";
+export const DEFAULT_LMSTUDIO_BASE_URL = "http://localhost:1234/v1";
+/** Built-in provider definitions (lowest priority — rc/env override). */
+export const BUILTIN_PROVIDERS = {
+    openai: { id: "openai", baseUrl: "https://api.openai.com/v1", apiKeyEnv: "OPENAI_API_KEY", kind: "openai" },
+    anthropic: {
+        id: "anthropic",
+        baseUrl: "https://api.anthropic.com/v1",
+        apiKeyEnv: "ANTHROPIC_API_KEY",
+        kind: "anthropic",
+        supportCache: true,
+        supportReasoning: true,
+    },
+    "openai-compatible": { id: "openai-compatible", baseUrl: "", apiKeyEnv: "SCODER_API_KEY", kind: "openai" },
+    ollama: { id: "ollama", baseUrl: DEFAULT_OLLAMA_BASE_URL, apiKeyEnv: "OLLAMA_API_KEY", kind: "openai", supportReasoning: true },
+    gemini: { id: "gemini", baseUrl: DEFAULT_GEMINI_BASE_URL, apiKeyEnv: "GEMINI_API_KEY", kind: "openai" },
+};
+/** Create the concrete runtime for a provider def. */
+export function createRuntime(def, opts) {
+    const common = {
+        baseUrl: opts.baseUrl || def.baseUrl,
+        apiKey: opts.apiKey,
+        model: opts.model,
+        maxTokens: opts.maxTokens,
+        temperature: opts.temperature,
+        enableCache: opts.enableCache ?? def.supportCache,
+    };
+    if (def.kind === "anthropic")
+        return new AnthropicClient(common);
+    return new LlmClient({ ...common, stream: opts.stream });
+}
+/** A configured custom provider from rc: providers.<id> = {baseUrl, apiKeyEnv, kind, ...}. */
+export function parseCustomProviders(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return {};
+    const out = {};
+    for (const [id, v] of Object.entries(raw)) {
+        if (typeof v !== "object" || v === null)
+            continue;
+        const d = v;
+        if (typeof d.baseUrl !== "string" || !d.baseUrl)
+            continue;
+        out[id] = {
+            id,
+            baseUrl: d.baseUrl,
+            apiKeyEnv: typeof d.apiKeyEnv === "string" ? d.apiKeyEnv : "SCODER_API_KEY",
+            kind: d.kind === "anthropic" ? "anthropic" : "openai",
+            supportCache: d.supportCache === true,
+            supportReasoning: d.supportReasoning === true,
+        };
+    }
+    return out;
+}
+/**
+ * Resolve a provider id → def. Model may be "provider/model" (splits).
+ * Returns null with a clean reason when the key env var is missing.
+ */
+export function resolveProvider(id, custom = {}) {
+    const def = custom[id] ?? BUILTIN_PROVIDERS[id];
+    if (!def) {
+        return { error: `unknown provider "${id}" — available: ${Object.keys({ ...BUILTIN_PROVIDERS, ...custom }).join(", ")}` };
+    }
+    return { def };
+}
+/** Split "provider/model" syntax; returns [provider, model] (unchanged when no slash). */
+export function splitProviderModel(model) {
+    const idx = model.indexOf("/");
+    if (idx <= 0)
+        return [null, model];
+    // anthropic/claude-x, openai/gpt-4o, groq/llama-3…
+    return [model.slice(0, idx), model.slice(idx + 1)];
+}
+const LOCAL_PROBES = [
+    { id: "ollama", baseUrl: DEFAULT_OLLAMA_BASE_URL },
+    { id: "lmstudio", baseUrl: DEFAULT_LMSTUDIO_BASE_URL },
+    { id: "vllm", baseUrl: "http://localhost:8000/v1" },
+];
+/**
+ * Probe local engines (300ms timeout each, concurrent). Returns engines that
+ * answered /v1/models with a valid list. Never throws; offline-safe.
+ */
+export async function discoverLocalEngines(timeoutMs = 300) {
+    const probes = await Promise.allSettled(LOCAL_PROBES.map(async (p) => {
+        const res = await fetch(`${p.baseUrl}/models`, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const models = (data.data ?? []).map((m) => m.id ?? "").filter(Boolean);
+        if (models.length === 0)
+            return null;
+        const builtin = BUILTIN_PROVIDERS[p.id];
+        const def = builtin ?? { id: p.id, baseUrl: p.baseUrl, apiKeyEnv: "SCODER_API_KEY", kind: "openai" };
+        return { provider: def, models };
+    }));
+    return probes
+        .filter((r) => r.status === "fulfilled")
+        .map((r) => r.value)
+        .filter((v) => v !== null);
+}

package/dist/retry.js

@@ -21,7 +21,7 @@ function sleep(ms) {
  * fail immediately via NonRetryableError semantics.
  */
 export async function withRetry(fn, opts = {}, onRetry) {
-    const maxRetries = opts.maxRetries ?? 3;
+    const maxRetries = opts.maxRetries ?? 4;
     const baseDelayMs = opts.baseDelayMs ?? 1000;
     const maxDelayMs = opts.maxDelayMs ?? 30_000;
     let lastErr;
@@ -44,7 +44,8 @@ export async function withRetry(fn, opts = {}, onRetry) {
             // Respect Retry-After header if present (seconds)
             const retryAfter = err.retryAfterMs;
             const jitter = Math.floor(Math.random() * 500);
-            const delay = Math.min(retryAfter ?? baseDelayMs * 2 ** attempt + jitter, maxDelayMs);
+            const rawDelay = retryAfter ?? baseDelayMs * 2 ** attempt + jitter;
+            const delay = Math.min(rawDelay, maxDelayMs);
             onRetry?.(attempt + 1, delay, status ? `HTTP ${status}` : String(err.message).slice(0, 80));
             await sleep(delay);
         }

package/dist/sandbox.js

@@ -0,0 +1,96 @@
+/**
+ * G4: Sandbox layer cho run_command (pattern từ opencode environment drivers —
+ * detection-first, không hard-depend).
+ *
+ * Profiles:
+ *  - "readonly"        — đọc được mọi nơi, ghi chỉ trong workspace
+ *  - "workspace-write" — ghi trong workspace (+TMPDIR), mạng vẫn mở
+ *
+ * Có wrapper binary (sandbox-exec / bwrap / docker) → wrap lệnh. Không có →
+ * trả về null (caller chạy trực tiếp + warn). ponytail: docker wrap chỉ build
+ * args cơ bản (volume workspace, không network flag) — nâng cấp image/network
+ * khi có nhu cầu thực.
+ */
+/** Workspace + temp dirs a command may always touch. */
+export function sandboxWritePaths(workdir) {
+    return [workdir, "/tmp", "/private/tmp"];
+}
+/** Build the wrapper argv for a profile. Pure — unit-test được. */
+export function buildSandboxArgv(wrapper, profile, workdir, command) {
+    const writes = sandboxWritePaths(workdir);
+    if (wrapper === "sandbox-exec") {
+        // macOS Seatbelt: một profile string param, readonly chặn file-write-*.
+        // Seatbelt đánh giá theo resolved path — /var/folders là symlink của
+        // /private/var/folders, nên subpath phải phủ cả hai dạng.
+        let realWs = workdir;
+        try {
+            realWs = realpathSync(workdir);
+        }
+        catch { /* nonexistent — raw path đủ */ }
+        const wsSubpaths = [...new Set([workdir, realWs])]
+            .map((p) => `(subpath "${p}/")`)
+            .join(" ");
+        const allowWrites = profile === "workspace-write"
+            ? `(allow file-write* ${wsSubpaths} (subpath "/tmp") (subpath "/private/tmp"))`
+            : `(deny file-write*)`;
+        const profileSbp = `(version 1)(deny default)(allow process*)(allow system-socket)(allow file-read*)(allow network*)(allow mach-lookup)(allow sysctl-read)${allowWrites}`;
+        return [
+            "sandbox-exec",
+            "-p", profileSbp,
+            "/bin/sh", "-c", command,
+        ];
+    }
+    if (wrapper === "bwrap") {
+        // bubblewrap: bind ro toàn hệ thống, rw workspace; unshare all để isolate.
+        const args = [
+            "bwrap",
+            "--dev-bind", "/", "/", // giữ root — sandbox theo write-permission, không chroot
+            "--ro-bind", "/", "/", // override: mọi mount ro
+        ];
+        for (const w of writes)
+            args.push("--bind", w, w);
+        if (profile === "readonly")
+            args.pop(); // readOnly: bỏ rw workspace
+        args.push("--", "/bin/sh", "-c", command);
+        return args;
+    }
+    // docker: volume workspace rw/ro, mount proc, no network isolation flag
+    // (network giữ mở — nâng cấp khi cần).
+    const roFlag = profile === "readonly" ? ":ro" : "";
+    return [
+        "docker", "run", "--rm",
+        "-v", `${workdir}:/workspace${roFlag}`,
+        "-w", "/workspace",
+        "--entrypoint", "/bin/sh",
+        "node:22-alpine",
+        "-c", command,
+    ];
+}
+/**
+ * Detect available wrapper và trả plan, hoặc null khi không sandbox được
+ * (caller: chạy trực tiếp + warn — never hard-fail).
+ */
+export function planSandbox(cfg, workdir, command) {
+    const mode = cfg.mode ?? "off";
+    if (mode === "off")
+        return null;
+    const wrapper = cfg.wrapper ?? (process.platform === "darwin" ? "sandbox-exec" : "bwrap");
+    return { wrapper, profile: mode, argv: buildSandboxArgv(wrapper, mode, workdir, command) };
+}
+/**
+ * Spawn argv qua sandbox khi có plan; nếu wrapper binary thiếu trên máy →
+ * null (fallback chạy trực tiếp). Async để dùng which-like check nhẹ.
+ */
+export async function resolveSandbox(cfg, workdir, command) {
+    const plan = planSandbox(cfg, workdir, command);
+    if (!plan)
+        return { argv: null, wrapper: null, reason: "sandbox off" };
+    // `which` không có trên Windows — dùng `where`.
+    const check = spawnSync(process.platform === "win32" ? "where" : "which", [plan.wrapper], { encoding: "utf8" });
+    if (check.status !== 0) {
+        return { argv: null, wrapper: null, reason: `${plan.wrapper} not found — running unsandboxed` };
+    }
+    return { argv: plan.argv.map(String), wrapper: plan.wrapper };
+}
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";

package/dist/server.js

@@ -197,7 +197,7 @@ export function startServer(baseConfig, opts = {}) {
             return;
         }
         // ── /api/runs/:id[...] ──
-        const runMatch = path.match(/^\/api\/runs\/([0-9a-f-]{36})(\/events|\/abort)?$/i);
+        const runMatch = path.match(/^\/api\/runs\/([0-9a-f-]{36})(\/events|\/abort|\/steer)?$/i);
         if (runMatch) {
             const record = runs.get(runMatch[1]);
             if (!record) {
@@ -218,6 +218,33 @@ export function startServer(baseConfig, opts = {}) {
                 sendJson(res, 200, { ok: true, status: "running (aborting...)" });
                 return;
             }
+            if (runMatch[2] === "/steer" && req.method === "POST") {
+                if (record.status !== "running" || !record.agent) {
+                    sendJson(res, 409, { error: `run is not running (status: ${record.status})` });
+                    return;
+                }
+                let body = "";
+                req.on("data", (c) => {
+                    body += c.toString();
+                    if (body.length > 1_000_000)
+                        req.destroy(); // 1MB cap
+                });
+                req.on("end", () => {
+                    try {
+                        const text = JSON.parse(body).text;
+                        if (typeof text !== "string" || !text.trim()) {
+                            sendJson(res, 400, { error: "body must be {text: string}" });
+                            return;
+                        }
+                        record.agent?.steer(text);
+                        sendJson(res, 200, { ok: true, delivered: "next step boundary" });
+                    }
+                    catch {
+                        sendJson(res, 400, { error: "invalid JSON body" });
+                    }
+                });
+                return;
+            }
             if (!runMatch[2] && req.method === "GET") {
                 sendJson(res, 200, publicRun(record));
                 return;