pentesting 0.73.2 → 0.73.3

package/dist/agent-tool-JEFUBDZE.js

@@ -0,0 +1,989 @@
+import {
+  CategorizedToolRegistry,
+  CoreAgent,
+  buildShellSupervisorLifecycleSection,
+  createContextExtractor,
+  getLLMClient,
+  getShellSupervisorLifecycleSnapshot
+} from "./chunk-BKWCGMSV.js";
+import {
+  AGENT_ROLES,
+  EVENT_TYPES,
+  LLM_ROLES,
+  TOOL_NAMES,
+  getProcessOutput,
+  listBackgroundProcesses
+} from "./chunk-UB7RW6LM.js";
+import {
+  DETECTION_PATTERNS,
+  PROCESS_EVENTS,
+  PROCESS_ROLES,
+  getActiveProcessSummary,
+  getProcessEventLog
+} from "./chunk-GLO6TOJN.js";
+
+// src/engine/agent-tool/completion-box.ts
+function createCompletionBox() {
+  return { done: false, result: null };
+}
+
+// src/engine/agent-tool/task-complete.ts
+function createTaskCompleteTool(completion) {
+  return {
+    name: TOOL_NAMES.TASK_COMPLETE,
+    description: `Signal task completion. Call this when the delegated task is done.
+Include all findings and loot discovered during the task.
+Use status: 'success' if goal achieved, 'partial' if partially done, 'failed' if blocked.
+Use 'waiting' or 'running' when the task created a durable operational asset that should be resumed later.`,
+    parameters: {
+      status: {
+        type: "string",
+        enum: ["success", "partial", "failed", "waiting", "running"],
+        description: "Task completion status"
+      },
+      summary: {
+        type: "string",
+        description: "What was accomplished (or why it failed)"
+      },
+      tried: {
+        type: "array",
+        items: { type: "string" },
+        description: "Approaches attempted during the task"
+      },
+      findings: {
+        type: "array",
+        items: { type: "string" },
+        description: "Security findings discovered (summary for main loop)"
+      },
+      loot: {
+        type: "array",
+        items: { type: "string" },
+        description: "Credentials, flags, or sensitive data obtained"
+      },
+      sessions: {
+        type: "array",
+        items: { type: "string" },
+        description: "Active session IDs established during the task"
+      },
+      assets: {
+        type: "array",
+        items: { type: "string" },
+        description: "Operational assets established during the task (listeners, shells, payloads, etc.)"
+      },
+      suggested_next: {
+        type: "string",
+        description: "Recommended next action for the main agent"
+      },
+      waiting_on: {
+        type: "string",
+        description: "External event or condition the task is waiting on"
+      },
+      resume_hint: {
+        type: "string",
+        description: "How the task should be resumed later"
+      },
+      next_worker_type: {
+        type: "string",
+        enum: ["general", "shell-supervisor", "exploit", "pwn"],
+        description: "Recommended worker type for the next delegated step"
+      }
+    },
+    required: ["status", "summary"],
+    execute: async (params) => {
+      const result = {
+        status: params["status"] ?? "partial",
+        summary: params["summary"] ?? "",
+        tried: params["tried"] ?? [],
+        findings: params["findings"] ?? [],
+        loot: params["loot"] ?? [],
+        sessions: params["sessions"] ?? [],
+        assets: params["assets"] ?? [],
+        suggestedNext: params["suggested_next"] ?? "",
+        waitingOn: params["waiting_on"] ?? void 0,
+        resumeHint: params["resume_hint"] ?? void 0,
+        nextWorkerType: params["next_worker_type"] ?? void 0
+      };
+      completion.done = true;
+      completion.result = result;
+      return {
+        success: true,
+        output: [
+          "[TASK_COMPLETE]",
+          `[Status] ${result.status}`,
+          `[Summary] ${result.summary}`,
+          result.waitingOn ? `[Waiting] ${result.waitingOn}` : "",
+          result.resumeHint ? `[Resume] ${result.resumeHint}` : ""
+        ].join("\n")
+      };
+    }
+  };
+}
+
+// src/engine/agent-tool/agent-registry.ts
+var AgentRegistry = class extends CategorizedToolRegistry {
+  constructor(state, scopeGuard, approvalGate, events, completion) {
+    super(state, scopeGuard, approvalGate, events);
+    const taskCompleteTool = createTaskCompleteTool(completion);
+    this.tools.set(taskCompleteTool.name, taskCompleteTool);
+  }
+  initializeRegistry() {
+    super.initializeRegistry();
+    this.tools.delete(TOOL_NAMES.RUN_TASK);
+    this.tools.delete(TOOL_NAMES.ASK_USER);
+  }
+};
+
+// src/engine/agent-tool/agent-runner.ts
+var MAX_AGENT_TOOL_ITERATIONS = 30;
+var COMPRESS_EVERY_N_STEPS = 5;
+var MAX_COMPRESS_FAILURES = 3;
+var AgentRunner = class extends CoreAgent {
+  completion;
+  contextExtractor;
+  stepCount = 0;
+  consecutiveCompressFailures = 0;
+  constructor(state, events, registry, completion) {
+    super({
+      agentType: AGENT_ROLES.AGENT_TOOL,
+      state,
+      events,
+      toolRegistry: registry,
+      maxIterations: MAX_AGENT_TOOL_ITERATIONS
+    });
+    this.completion = completion;
+    this.contextExtractor = createContextExtractor(getLLMClient());
+  }
+  /**
+   * CoreAgent.step() 오버라이드
+   *
+   * 추가 동작 (super.step() 이후):
+   *   1. completion.done 확인 → task_complete 호출됐으면 즉시 완료 신호
+   *   2. COMPRESS_EVERY_N_STEPS마다 ContextExtractor 호출
+   */
+  async step(iteration, messages, systemPrompt, progress) {
+    const result = await super.step(iteration, messages, systemPrompt, progress);
+    if (this.completion.done) {
+      return {
+        output: JSON.stringify(this.completion.result),
+        toolsExecuted: result.toolsExecuted,
+        isCompleted: true
+      };
+    }
+    this.stepCount++;
+    if (this.stepCount % COMPRESS_EVERY_N_STEPS === 0) {
+      await this.compressContext(messages);
+    }
+    return result;
+  }
+  /**
+   * ContextExtractor를 사용해 messages[]를 1개 session-context로 압축.
+   *
+   * WHY: 실패 시 무시 (try/catch). CoreAgent의 trimMessagesIfNeeded(50)이
+   * 최후 안전망이므로 압축 실패가 치명적이지 않다.
+   * WHY (failure tracking): 연속 실패가 MAX_COMPRESS_FAILURES 초과 시 경고 emit.
+   * sub-agent가 초기 task를 잃어버릴 위험을 TUI에 노출해 사용자가 인지할 수 있게 한다.
+   */
+  async compressContext(messages) {
+    try {
+      const result = await this.contextExtractor.execute({ messages });
+      if (result.success && result.extractedContext) {
+        messages.length = 0;
+        messages.push({
+          role: LLM_ROLES.USER,
+          content: `<session-context>
+${result.extractedContext}
+</session-context>`
+        });
+        this.consecutiveCompressFailures = 0;
+      }
+    } catch {
+      this.consecutiveCompressFailures++;
+      if (this.consecutiveCompressFailures === MAX_COMPRESS_FAILURES) {
+        this.events.emit({
+          type: EVENT_TYPES.NOTIFICATION,
+          timestamp: Date.now(),
+          data: {
+            title: "Sub-Agent Context Warning",
+            message: `Context compression failed ${this.consecutiveCompressFailures}x in a row. Sub-agent may lose task direction. Consider reducing task scope.`,
+            level: "warning"
+          }
+        });
+      }
+    }
+  }
+};
+
+// src/engine/agent-tool/agent-prompt.ts
+function buildAgentPrompt(input, workerExecutor) {
+  const parts = [
+    "You are an autonomous execution agent. Complete the delegated task using available tools.",
+    "",
+    `## Task
+${input.task}`
+  ];
+  if (input.target) {
+    parts.push(`
+## Target
+${input.target}`);
+  }
+  if (input.context) {
+    parts.push(`
+## Context
+${input.context}`);
+  }
+  const activeProcesses = getActiveProcessSummary();
+  if (activeProcesses) {
+    parts.push(`
+## Active Background Processes
+${activeProcesses}`);
+  }
+  if (workerExecutor) {
+    for (const section of workerExecutor.buildPromptSections(input)) {
+      parts.push(`
+${section}`);
+    }
+  }
+  parts.push(`
+## Rules
+- Do NOT call ask_user. You are autonomous. Make your best judgment.
+- Call task_complete when the task is done (status: success, partial, failed, waiting, or running).
+- Record findings with add_finding, loot with add_loot as you discover them.
+- If you hit 3 consecutive failures on the same approach, switch vectors or declare failed.
+- Use waiting/running when you created a durable operational asset that should be resumed later.
+- Be decisive \u2014 do not loop indefinitely on the same approach.`);
+  return parts.join("\n");
+}
+
+// src/engine/agent-tool/worker-executor.ts
+function joinContextParts(parts) {
+  const filtered = parts.filter(Boolean);
+  if (filtered.length === 0) return void 0;
+  return filtered.join("\n\n");
+}
+function buildWorkerGuidance(input) {
+  switch (input.workerType) {
+    case "shell-supervisor":
+      return [
+        "## Worker Specialization",
+        "You are the shell-supervisor worker.",
+        "",
+        "- Prioritize reusing existing listeners, shell sessions, and promoted shell assets.",
+        "- First action: inspect relevant background processes and detect whether a connection already landed.",
+        "- If a listener has a connection, promote it before launching any new listener.",
+        "- Validate shell quality quickly: whoami, id, hostname, pwd, uname -a.",
+        "- If the shell is dumb, attempt PTY upgrade and shell stabilization immediately.",
+        "- After stabilization, continue lightweight post-exploitation enumeration using the existing shell.",
+        "- Do not create duplicate listeners unless the current asset is clearly dead."
+      ].join("\n");
+    case "exploit":
+      return [
+        "## Worker Specialization",
+        "You are the exploit worker.",
+        "",
+        "- Focus on exploit chain execution and branching follow-up.",
+        "- Prefer adapting the current vector before switching to an unrelated attack.",
+        "- Record what was tried and why each branch succeeded or failed."
+      ].join("\n");
+    case "pwn":
+      return [
+        "## Worker Specialization",
+        "You are the pwn worker.",
+        "",
+        "- Focus on iterative exploit development, repeated run/debug cycles, and precise observations.",
+        "- Preserve crash details, offsets, gadgets, payload changes, and solver state."
+      ].join("\n");
+    default:
+      return "";
+  }
+}
+var DefaultDelegatedWorkerExecutor = class {
+  prepareInput(input) {
+    return input;
+  }
+  buildPromptSections(input) {
+    const guidance = buildWorkerGuidance(input);
+    return guidance ? [guidance] : [];
+  }
+  finalizeResult(_input, result) {
+    return result;
+  }
+};
+function mergeWorkerContext(input, extraContext) {
+  return {
+    ...input,
+    context: joinContextParts([input.context, extraContext])
+  };
+}
+
+// src/engine/agent-tool/exploit-worker-plan.ts
+function getContextValue(context, key) {
+  if (!context) return null;
+  const match = context.match(new RegExp(`${key}=([^|\\n]+)`));
+  return match?.[1]?.trim() ?? null;
+}
+function buildExploitWorkerPlan(input) {
+  const phase = getContextValue(input.context, "exploit_phase") || "vector_active";
+  if (phase === "foothold_active") {
+    return [
+      "## Exploit Worker Plan",
+      "Immediate actions:",
+      "1. Reuse the current foothold before launching any new exploit branch.",
+      '2. Prefer exploit_foothold_check(command="...") for bounded access validation before broadening the chain.',
+      "3. Validate what that foothold can already reach or dump.",
+      "4. Continue the exploit chain from the live access path instead of restarting delivery."
+    ].join("\n");
+  }
+  if (phase === "credential_followup") {
+    return [
+      "## Exploit Worker Plan",
+      "Immediate actions:",
+      "1. Validate the dumped credentials or tokens first.",
+      '2. Prefer exploit_credential_check(command="...") for bounded credential/token validation before changing vectors.',
+      "3. Reuse them against the current target or nearest pivot target before changing vectors.",
+      "4. If reuse succeeds, convert that into a foothold and report it explicitly."
+    ].join("\n");
+  }
+  if (phase === "artifact_ready") {
+    return [
+      "## Exploit Worker Plan",
+      "Immediate actions:",
+      "1. Validate the current exploit artifact before building a replacement.",
+      '2. Prefer exploit_artifact_check(command="...") for bounded artifact verification.',
+      "3. Keep the artifact tied to the current exploit chain in assets.",
+      "4. If the artifact lands access or data, pivot the chain from that result."
+    ].join("\n");
+  }
+  return [
+    "## Exploit Worker Plan",
+    "Immediate actions:",
+    "1. Continue the strongest surviving exploit vector.",
+    "2. Preserve branch decisions and observed responses.",
+    "3. Only switch vectors after concrete failure evidence."
+  ].join("\n");
+}
+
+// src/engine/agent-tool/exploit-worker.ts
+function getContextValue2(context, key) {
+  if (!context) return null;
+  const match = context.match(new RegExp(`${key}=([^|\\n]+)`));
+  return match?.[1]?.trim() ?? null;
+}
+function getExploitPhase(context) {
+  return getContextValue2(context, "exploit_phase") || "vector_active";
+}
+function getRecommendation(context) {
+  return getContextValue2(context, "recommendation");
+}
+function buildExploitExecutionPolicy() {
+  return [
+    "## Exploit Worker Execution Policy",
+    "- Treat exploit work as a branching chain, not a one-shot attempt.",
+    "- Preserve the current vector unless concrete evidence says it is dead.",
+    '- If the chain created a durable artifact or needs another exploit iteration, prefer status="running".',
+    "- Record payload variants, observed responses, and why each branch succeeded or failed."
+  ].join("\n");
+}
+function buildExploitLifecycleSection(input) {
+  const phase = getExploitPhase(input.context);
+  const recommendation = getRecommendation(input.context) || "Continue the current exploit chain before switching vectors.";
+  return [
+    "## Exploit Lifecycle",
+    `Current phase: ${phase}`,
+    `Recommendation: ${recommendation}`
+  ].join("\n");
+}
+function buildExploitCompletionGuidance(input) {
+  const phase = getExploitPhase(input.context);
+  if (phase === "foothold_active") {
+    return [
+      "## Exploit Completion Guidance",
+      'If the chain already has a foothold, prefer status="running" and report the session/asset explicitly.',
+      "Resume hint should keep the current foothold as the primary access path."
+    ].join("\n");
+  }
+  if (phase === "credential_followup") {
+    return [
+      "## Exploit Completion Guidance",
+      'If the chain produced credentials or tokens, prefer status="running" until reuse or validation is complete.',
+      "Record loot explicitly and resume from credential validation before changing exploit vectors."
+    ].join("\n");
+  }
+  if (phase === "artifact_ready") {
+    return [
+      "## Exploit Completion Guidance",
+      'If the chain produced a reusable artifact, prefer status="running" until the artifact is validated or consumed.',
+      "Report the artifact in assets and keep resumeHint focused on that artifact."
+    ].join("\n");
+  }
+  return [
+    "## Exploit Completion Guidance",
+    'If the current vector remains viable but incomplete, prefer status="running" and keep the resume hint tied to the strongest surviving vector.'
+  ].join("\n");
+}
+var ExploitWorker = class extends DefaultDelegatedWorkerExecutor {
+  buildPromptSections(input) {
+    return [
+      ...super.buildPromptSections(input),
+      buildExploitLifecycleSection(input),
+      buildExploitExecutionPolicy(),
+      buildExploitWorkerPlan(input),
+      buildExploitCompletionGuidance(input)
+    ];
+  }
+  finalizeResult(input, result) {
+    const phase = getExploitPhase(input.context);
+    const resumeHint = phase === "foothold_active" ? "Reuse the current foothold and continue the exploit chain from that access path." : phase === "credential_followup" ? "Validate and reuse the obtained credentials or tokens before changing exploit vectors." : phase === "artifact_ready" ? "Validate and advance the current exploit artifact before switching vectors." : "Continue the current exploit chain from the strongest surviving vector.";
+    const waitingOn = phase === "foothold_active" ? "follow-up work on the current foothold such as privilege escalation or pivot preparation" : phase === "credential_followup" ? "credential or token validation and reuse" : phase === "artifact_ready" ? "artifact validation or consumption" : "next exploit chain step or artifact validation";
+    if (result.status === "success" || result.status === "partial") {
+      return {
+        ...result,
+        status: result.assets.length > 0 || result.sessions.length > 0 || Boolean(result.resumeHint) ? "running" : result.status,
+        waitingOn: result.waitingOn ?? (result.status === "success" ? void 0 : waitingOn),
+        resumeHint: result.resumeHint ?? (result.status === "success" ? void 0 : resumeHint),
+        nextWorkerType: result.nextWorkerType ?? "exploit"
+      };
+    }
+    return {
+      ...result,
+      nextWorkerType: result.nextWorkerType ?? "exploit"
+    };
+  }
+};
+
+// src/engine/agent-tool/pwn-worker-plan.ts
+function getContextValue3(context, key) {
+  if (!context) return null;
+  const match = context.match(new RegExp(`${key}=([^|\\n]+)`));
+  return match?.[1]?.trim() ?? null;
+}
+function buildPwnWorkerPlan(input) {
+  const phase = getContextValue3(input.context, "pwn_phase") || "payload_iteration";
+  if (phase === "foothold_active") {
+    return [
+      "## Pwn Worker Plan",
+      "Immediate actions:",
+      "1. Reuse the achieved execution foothold before reopening the exploit loop.",
+      "2. Convert that execution into objective completion or post-exploitation steps.",
+      "3. Preserve the working exploit state as the current best chain."
+    ].join("\n");
+  }
+  if (phase === "offset_known") {
+    return [
+      "## Pwn Worker Plan",
+      "Immediate actions:",
+      "1. Resume from the known offset and latest payload revision.",
+      '2. Prefer pwn_offset_check(command="...") for bounded control verification.',
+      "3. Avoid recomputing control primitives that are already established.",
+      "4. Focus the next iteration on reliable code execution or leak stabilization."
+    ].join("\n");
+  }
+  if (phase === "crash_iteration") {
+    return [
+      "## Pwn Worker Plan",
+      "Immediate actions:",
+      "1. Reproduce the latest crash exactly.",
+      '2. Prefer pwn_crash_repro(command="...") for bounded crash reproduction.',
+      "3. Preserve crash evidence, registers, and payload delta from the last iteration.",
+      "4. Move one step closer to control, leak, or execution rather than restarting analysis."
+    ].join("\n");
+  }
+  return [
+    "## Pwn Worker Plan",
+    "Immediate actions:",
+    "1. Continue the active payload-design loop.",
+    '2. Prefer pwn_payload_smoke(command="...") for the narrowest next payload test.',
+    "3. Preserve each payload revision and observable behavior.",
+    "4. Make the next test iteration narrower, not broader."
+  ].join("\n");
+}
+
+// src/engine/agent-tool/pwn-worker.ts
+function getContextValue4(context, key) {
+  if (!context) return null;
+  const match = context.match(new RegExp(`${key}=([^|\\n]+)`));
+  return match?.[1]?.trim() ?? null;
+}
+function getPwnPhase(context) {
+  return getContextValue4(context, "pwn_phase") || "payload_iteration";
+}
+function getRecommendation2(context) {
+  return getContextValue4(context, "recommendation");
+}
+function buildPwnExecutionPolicy() {
+  return [
+    "## Pwn Worker Execution Policy",
+    "- Treat pwn work as an iterative solver loop with repeatable checkpoints.",
+    "- Preserve offsets, crash signatures, gadgets, leaked pointers, and payload revisions.",
+    '- If another debug or payload iteration is required, prefer status="running".',
+    "- Make the next iteration obvious in resumeHint rather than restarting from scratch."
+  ].join("\n");
+}
+function buildPwnLifecycleSection(input) {
+  const phase = getPwnPhase(input.context);
+  const recommendation = getRecommendation2(input.context) || "Continue from the latest crash, offset, or payload revision.";
+  return [
+    "## Pwn Lifecycle",
+    `Current phase: ${phase}`,
+    `Recommendation: ${recommendation}`
+  ].join("\n");
+}
+function buildPwnCompletionGuidance(input) {
+  const phase = getPwnPhase(input.context);
+  if (phase === "foothold_active") {
+    return [
+      "## Pwn Completion Guidance",
+      'If the pwn chain already has execution, prefer status="running" and keep the existing foothold as the primary path.'
+    ].join("\n");
+  }
+  if (phase === "offset_known") {
+    return [
+      "## Pwn Completion Guidance",
+      'If offsets are known but the exploit is incomplete, prefer status="running" and resume from the known control primitive.'
+    ].join("\n");
+  }
+  if (phase === "crash_iteration") {
+    return [
+      "## Pwn Completion Guidance",
+      'If a crash state exists, prefer status="running" and resume from the preserved crash evidence rather than restarting.'
+    ].join("\n");
+  }
+  return [
+    "## Pwn Completion Guidance",
+    'If the payload loop is still active, prefer status="running" and make the next payload iteration explicit.'
+  ].join("\n");
+}
+var PwnWorker = class extends DefaultDelegatedWorkerExecutor {
+  buildPromptSections(input) {
+    return [
+      ...super.buildPromptSections(input),
+      buildPwnLifecycleSection(input),
+      buildPwnExecutionPolicy(),
+      buildPwnWorkerPlan(input),
+      buildPwnCompletionGuidance(input)
+    ];
+  }
+  finalizeResult(input, result) {
+    const phase = getPwnPhase(input.context);
+    const resumeHint = phase === "foothold_active" ? "Reuse the existing execution foothold and continue objective completion from that access path." : phase === "offset_known" ? "Resume from the known offset and latest payload revision." : phase === "crash_iteration" ? "Resume from the latest crash state, preserved offsets, and debugger observations." : "Resume from the latest payload revision and solver observations.";
+    const waitingOn = phase === "foothold_active" ? "follow-up work on the existing execution foothold" : phase === "offset_known" ? "next payload iteration from the known offset" : phase === "crash_iteration" ? "next exploit-development or debugging iteration" : "next payload-design iteration";
+    if (result.status === "success" || result.status === "partial") {
+      return {
+        ...result,
+        status: result.status === "partial" || Boolean(result.resumeHint) ? "running" : result.status,
+        waitingOn: result.waitingOn ?? (result.status === "partial" ? waitingOn : void 0),
+        resumeHint: result.resumeHint ?? (result.status === "partial" ? resumeHint : void 0),
+        nextWorkerType: result.nextWorkerType ?? "pwn"
+      };
+    }
+    return {
+      ...result,
+      nextWorkerType: result.nextWorkerType ?? "pwn"
+    };
+  }
+};
+
+// src/engine/agent-tool/shell-supervisor-action-plan.ts
+function buildShellSupervisorActionPlan() {
+  const snapshot = getShellSupervisorLifecycleSnapshot();
+  if (snapshot.phase === "active_shell_ready" && snapshot.activeShellId) {
+    return [
+      "## Shell Supervisor Action Plan",
+      "Immediate actions:",
+      `1. Reuse the existing shell first: shell_check({ process_id: "${snapshot.activeShellId}", profile: "identity" })`,
+      `2. Confirm environment: shell_exec({ process_id: "${snapshot.activeShellId}", command: "pwd && uname -a" })`,
+      `3. If the shell is unstable or dumb, run shell_upgrade({ process_id: "${snapshot.activeShellId}", method: "python_pty" }) before wider enumeration.`
+    ].join("\n");
+  }
+  if (snapshot.phase === "listener_callback_detected" && snapshot.listenerId) {
+    return [
+      "## Shell Supervisor Action Plan",
+      "Immediate actions:",
+      `1. Confirm listener output: listener_status({ process_id: "${snapshot.listenerId}" })`,
+      `2. Promote the callback path: shell_promote({ process_id: "${snapshot.listenerId}" })`,
+      `3. Validate the new shell: shell_check({ process_id: "${snapshot.listenerId}", profile: "identity" })`
+    ].join("\n");
+  }
+  if (snapshot.phase === "listener_waiting" && snapshot.listenerId) {
+    return [
+      "## Shell Supervisor Action Plan",
+      "Immediate actions:",
+      `1. Poll the current listener: listener_status({ process_id: "${snapshot.listenerId}" })`,
+      `2. Reuse ${snapshot.listenerId} unless status proves it is dead or unusable.`,
+      "3. Continue the exploit chain against the current callback path instead of opening a duplicate listener."
+    ].join("\n");
+  }
+  return [
+    "## Shell Supervisor Action Plan",
+    "Immediate actions:",
+    "1. No reusable shell asset exists yet. If a callback path is required, create exactly one listener with listener_start().",
+    "2. After launch, poll it with listener_status() and promote on connection with shell_promote() before creating any replacement."
+  ].join("\n");
+}
+
+// src/engine/agent-tool/shell-supervisor-completion-guidance.ts
+function formatList(values) {
+  return values.length > 0 ? values.map((value) => `"${value}"`).join(", ") : "";
+}
+function buildShellSupervisorCompletionGuidance() {
+  const snapshot = getShellSupervisorLifecycleSnapshot();
+  if (snapshot.phase === "active_shell_ready" && snapshot.activeShellId) {
+    const assets = [`shell:${snapshot.activeShellId}`];
+    return [
+      "## Shell Supervisor Completion Guidance",
+      "Preferred completion shape when a reusable shell already exists:",
+      "```text",
+      "task_complete({",
+      '  status: "running",',
+      '  summary: "Reused the active shell and kept the shell chain alive for follow-up.",',
+      `  sessions: [${formatList([snapshot.activeShellId])}],`,
+      `  assets: [${formatList(assets)}],`,
+      '  waiting_on: "shell follow-up actions such as PTY upgrade or host enumeration",',
+      `  resume_hint: "Reuse ${snapshot.activeShellId}, validate shell quality, upgrade PTY if needed, then continue enumeration.",`,
+      '  next_worker_type: "shell-supervisor"',
+      "})",
+      "```"
+    ].join("\n");
+  }
+  if ((snapshot.phase === "active_shell_stabilized" || snapshot.phase === "post_exploitation_active") && snapshot.activeShellId) {
+    const assets = [`shell:${snapshot.activeShellId}`, `stabilized_shell:${snapshot.activeShellId}`];
+    if (snapshot.phase === "post_exploitation_active") {
+      assets.push(`post_exploitation_shell:${snapshot.activeShellId}`);
+    }
+    return [
+      "## Shell Supervisor Completion Guidance",
+      snapshot.phase === "post_exploitation_active" ? "Preferred completion shape when a stabilized shell is already driving post-exploitation:" : "Preferred completion shape when a stabilized shell already exists:",
+      "```text",
+      "task_complete({",
+      '  status: "running",',
+      snapshot.phase === "post_exploitation_active" ? '  summary: "Reused the stabilized shell and kept the post-exploitation chain active for follow-up.",' : '  summary: "Reused the stabilized shell and kept it available for controlled follow-up.",',
+      `  sessions: [${formatList([snapshot.activeShellId])}],`,
+      `  assets: [${formatList(assets)}],`,
+      snapshot.phase === "post_exploitation_active" ? '  waiting_on: "controlled post-exploitation follow-up such as privilege escalation, credential harvesting, or pivot preparation",' : '  waiting_on: "controlled shell follow-up actions such as host enumeration or privilege escalation",',
+      snapshot.phase === "post_exploitation_active" ? `  resume_hint: "Reuse ${snapshot.activeShellId}, continue controlled post-exploitation through the existing shell, and avoid opening duplicate access paths.",` : `  resume_hint: "Reuse ${snapshot.activeShellId}, keep the stabilized shell as the primary access path, and continue controlled enumeration.",`,
+      '  next_worker_type: "shell-supervisor"',
+      "})",
+      "```"
+    ].join("\n");
+  }
+  if (snapshot.phase === "listener_callback_detected" && snapshot.listenerId) {
+    return [
+      "## Shell Supervisor Completion Guidance",
+      "Preferred completion shape when a listener has received a callback but promotion is still in progress:",
+      "```text",
+      "task_complete({",
+      '  status: "running",',
+      '  summary: "Detected a live callback on the listener and kept the shell acquisition chain active.",',
+      `  assets: [${formatList([`listener:${snapshot.listenerId}`])}],`,
+      '  waiting_on: "listener callback needs promotion and shell validation",',
+      `  resume_hint: "Check ${snapshot.listenerId}, promote it to an active shell, then interact and stabilize it.",`,
+      '  next_worker_type: "shell-supervisor"',
+      "})",
+      "```"
+    ].join("\n");
+  }
+  if (snapshot.phase === "listener_waiting" && snapshot.listenerId) {
+    return [
+      "## Shell Supervisor Completion Guidance",
+      "Preferred completion shape when supervision is waiting on an external callback:",
+      "```text",
+      "task_complete({",
+      '  status: "waiting",',
+      '  summary: "Listener remains active and is waiting for a reverse-shell callback.",',
+      `  assets: [${formatList([`listener:${snapshot.listenerId}`])}],`,
+      '  waiting_on: "incoming reverse-shell callback",',
+      `  resume_hint: "Poll ${snapshot.listenerId} with bg_process status, then promote immediately if a connection appears.",`,
+      '  next_worker_type: "shell-supervisor"',
+      "})",
+      "```",
+      "Do not mark this as failed just because the external callback has not arrived yet."
+    ].join("\n");
+  }
+  return [
+    "## Shell Supervisor Completion Guidance",
+    'If no listener or shell asset exists, only use status="failed" when the callback path is clearly broken.',
+    "If you created no durable asset, close with success/partial/failed and explain the next setup step explicitly."
+  ].join("\n");
+}
+
+// src/engine/agent-tool/shell-supervisor-context.ts
+var MAX_RELEVANT_PROCESSES = 3;
+var MAX_RELEVANT_EVENTS = 3;
+var MAX_SNIPPET_LINES = 3;
+function getRolePriority(role) {
+  switch (role) {
+    case PROCESS_ROLES.ACTIVE_SHELL:
+      return 0;
+    case PROCESS_ROLES.LISTENER:
+      return 1;
+    default:
+      return 2;
+  }
+}
+function getSnippet(stdout, stderr) {
+  const source = stdout.trim() || stderr.trim();
+  if (!source) return "";
+  const lines = source.split("\n").map((line) => line.trim()).filter(Boolean);
+  return lines.slice(-MAX_SNIPPET_LINES).join(" | ");
+}
+function getRecommendation3(role) {
+  if (role === PROCESS_ROLES.ACTIVE_SHELL) {
+    return "Reuse this shell first. Validate with whoami, id, hostname, pwd, and uname -a before expanding.";
+  }
+  if (role === PROCESS_ROLES.LISTENER) {
+    return "Check whether a connection landed before creating a new listener. Promote immediately if the callback is live.";
+  }
+  return "Reuse this process asset if it still matches the delegated objective.";
+}
+function buildShellSupervisorContext() {
+  const relevantProcesses = listBackgroundProcesses().filter((process) => process.isRunning && (process.role === PROCESS_ROLES.ACTIVE_SHELL || process.role === PROCESS_ROLES.LISTENER)).sort((left, right) => getRolePriority(left.role) - getRolePriority(right.role)).slice(0, MAX_RELEVANT_PROCESSES);
+  const relevantIds = new Set(relevantProcesses.map((process) => process.id));
+  const recentEvents = getProcessEventLog().filter((event) => relevantIds.has(event.processId)).slice(-MAX_RELEVANT_EVENTS);
+  if (relevantProcesses.length === 0 && recentEvents.length === 0) {
+    return "";
+  }
+  const lines = [
+    "## Shell Supervisor Context",
+    "Inspect these runtime assets before opening new listeners or spawning duplicate shells."
+  ];
+  if (relevantProcesses.length > 0) {
+    lines.push("Relevant Assets:");
+    for (const process of relevantProcesses) {
+      const output = getProcessOutput(process.id);
+      if (!output) continue;
+      const port = output.listeningPort ? ` port=${output.listeningPort}` : "";
+      const interactive = output.isInteractive ? " interactive=true" : "";
+      lines.push(`- ${process.id} [${output.role}]${port}${interactive} purpose=${output.purpose}`);
+      const snippet = getSnippet(output.stdout, output.stderr);
+      if (snippet) {
+        lines.push(`  Recent Output: ${snippet}`);
+      }
+      lines.push(`  Recommendation: ${getRecommendation3(output.role)}`);
+    }
+  }
+  if (recentEvents.length > 0) {
+    lines.push("Recent Events:");
+    for (const event of recentEvents) {
+      const ageSeconds = Math.round((Date.now() - event.timestamp) / 1e3);
+      lines.push(`- ${event.processId} ${event.event} (${ageSeconds}s ago): ${event.detail}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/engine/agent-tool/shell-supervisor-pty-playbook.ts
+function buildShellSupervisorPtyPlaybook() {
+  return [
+    "## Shell Supervisor PTY Upgrade Playbook",
+    "If the callback lands but the shell is dumb, try these in order and stop once one works:",
+    '0. Use `shell_check({ process_id: "...", profile: "stability" })` to confirm whether the shell is still dumb before widening the operation.',
+    "1. `python3 -c 'import pty;pty.spawn(\"/bin/bash\")'` or `python -c 'import pty;pty.spawn(\"/bin/bash\")'`",
+    '   Or send the bounded helper: `shell_upgrade({ process_id: "...", method: "python_pty" })`',
+    "2. `script -qc /bin/bash /dev/null` or `script /dev/null -c bash`",
+    '   Or send the bounded helper: `shell_upgrade({ process_id: "...", method: "script" })`',
+    "3. `perl -e 'exec \"/bin/bash\"'`, `ruby -e 'exec \"/bin/bash\"'`, or `/usr/bin/expect -c 'spawn bash; interact'`",
+    "4. After PTY spawn, finish stabilization on the attacker side with `stty raw -echo; fg`, then set `TERM`, `SHELL`, and terminal rows/columns.",
+    "5. If socat is present, prefer a socat PTY relay for a higher quality shell.",
+    "Do not expand into wide post-exploitation until the shell is at least minimally stable."
+  ].join("\n");
+}
+
+// src/engine/agent-tool/worker-preflight.ts
+function hasConnectionSignal(processId, stdout) {
+  if (DETECTION_PATTERNS.CONNECTION.some((pattern) => pattern.test(stdout))) {
+    return true;
+  }
+  return getProcessEventLog().some(
+    (event) => event.processId === processId && event.event === PROCESS_EVENTS.CONNECTION_DETECTED
+  );
+}
+function buildShellSupervisorPreflight() {
+  const processes = listBackgroundProcesses().filter(
+    (process) => process.isRunning && (process.role === PROCESS_ROLES.ACTIVE_SHELL || process.role === PROCESS_ROLES.LISTENER)
+  );
+  const activeShell = processes.find((process) => process.role === PROCESS_ROLES.ACTIVE_SHELL);
+  if (activeShell) {
+    return [
+      "## Shell Supervisor Preflight",
+      `Primary asset: ${activeShell.id} is already an active shell.`,
+      "First actions:",
+      "- Reuse this shell before opening any new listener.",
+      "- Validate shell quality with whoami, id, hostname, pwd, and uname -a.",
+      "- If the shell is unstable or dumb, upgrade PTY immediately."
+    ].join("\n");
+  }
+  const listeners = processes.filter((process) => process.role === PROCESS_ROLES.LISTENER);
+  for (const listener of listeners) {
+    const output = getProcessOutput(listener.id);
+    if (!output) continue;
+    if (hasConnectionSignal(listener.id, output.stdout)) {
+      return [
+        "## Shell Supervisor Preflight",
+        `Primary asset: ${listener.id} listener shows a callback signal.`,
+        "First actions:",
+        `- Check bg_process status for ${listener.id} before creating a new listener.`,
+        `- Promote ${listener.id} immediately if the callback is live.`,
+        `- After promotion, interact with ${listener.id} and validate shell quality.`
+      ].join("\n");
+    }
+  }
+  if (listeners.length > 0) {
+    return [
+      "## Shell Supervisor Preflight",
+      `Primary asset: ${listeners[0].id} listener is still running.`,
+      "First actions:",
+      `- Check bg_process status for ${listeners[0].id} before creating a duplicate listener.`,
+      "- Reuse the existing listener unless it is dead or clearly unsuitable.",
+      "- If no callback is present, continue the exploit chain against the existing listener."
+    ].join("\n");
+  }
+  return [
+    "## Shell Supervisor Preflight",
+    "No reusable listener or active shell is currently available.",
+    "First actions:",
+    "- If delegation needs a callback path, create one listener only.",
+    "- After launch, monitor it with bg_process status and promote on connection."
+  ].join("\n");
+}
+
+// src/engine/agent-tool/shell-supervisor-worker.ts
+function buildShellCompletionPolicy() {
+  return [
+    "## Shell Supervisor Completion Policy",
+    '- Use status="waiting" when a listener or shell asset must be supervised for an external event.',
+    '- Use status="running" when the shell chain is active but still needs additional delegated follow-up.',
+    "- Report shell assets explicitly in assets/sessions so the next resume step reuses them.",
+    "- If a shell is upgraded or stabilized, mention that in summary and resumeHint."
+  ].join("\n");
+}
+function uniq(values) {
+  return [...new Set(values)];
+}
+function getShellAssets(shellId, phase) {
+  const assets = [`shell:${shellId}`];
+  if (phase === "active_shell_stabilized" || phase === "post_exploitation_active") {
+    assets.push(`stabilized_shell:${shellId}`);
+  }
+  if (phase === "post_exploitation_active") {
+    assets.push(`post_exploitation_shell:${shellId}`);
+  }
+  return assets;
+}
+var ShellSupervisorWorker = class extends DefaultDelegatedWorkerExecutor {
+  prepareInput(input) {
+    return mergeWorkerContext(input, buildShellSupervisorPreflight());
+  }
+  buildPromptSections(input) {
+    const sections = super.buildPromptSections(input);
+    const shellContext = buildShellSupervisorContext();
+    if (shellContext) {
+      sections.unshift(shellContext);
+    }
+    sections.push(buildShellSupervisorLifecycleSection());
+    sections.push(buildShellSupervisorActionPlan());
+    sections.push(buildShellSupervisorPtyPlaybook());
+    sections.push(buildShellSupervisorCompletionGuidance());
+    sections.push(buildShellCompletionPolicy());
+    return sections;
+  }
+  finalizeResult(_input, result) {
+    const snapshot = getShellSupervisorLifecycleSnapshot();
+    if ((snapshot.phase === "active_shell_ready" || snapshot.phase === "active_shell_stabilizing" || snapshot.phase === "active_shell_stabilized" || snapshot.phase === "post_exploitation_active") && snapshot.activeShellId) {
+      const waitingOn = snapshot.phase === "post_exploitation_active" ? "controlled post-exploitation follow-up such as privilege escalation, credential harvesting, or pivot preparation" : snapshot.phase === "active_shell_stabilized" ? "controlled shell follow-up actions such as host enumeration or privilege escalation" : "shell follow-up actions such as PTY upgrade or host enumeration";
+      const resumeHint = snapshot.phase === "post_exploitation_active" ? `Reuse ${snapshot.activeShellId}, continue controlled post-exploitation through the existing shell, and avoid opening duplicate access paths.` : snapshot.phase === "active_shell_stabilized" ? `Reuse ${snapshot.activeShellId}, keep the stabilized shell as the primary access path, and continue controlled enumeration.` : snapshot.phase === "active_shell_stabilizing" ? `Reuse ${snapshot.activeShellId}, verify TERM/TTY quality, finish PTY stabilization, then continue enumeration.` : `Reuse ${snapshot.activeShellId}, validate shell quality, upgrade PTY if needed, then continue enumeration.`;
+      return {
+        ...result,
+        status: result.status === "success" || result.status === "partial" ? "running" : result.status,
+        sessions: uniq([...result.sessions, snapshot.activeShellId]),
+        assets: uniq([...result.assets, ...getShellAssets(snapshot.activeShellId, snapshot.phase)]),
+        waitingOn: result.waitingOn ?? waitingOn,
+        resumeHint: result.resumeHint ?? resumeHint,
+        nextWorkerType: result.nextWorkerType ?? "shell-supervisor"
+      };
+    }
+    if (snapshot.phase === "listener_callback_detected" && snapshot.listenerId) {
+      return {
+        ...result,
+        status: result.status === "success" || result.status === "partial" ? "running" : result.status,
+        assets: uniq([...result.assets, `listener:${snapshot.listenerId}`]),
+        waitingOn: result.waitingOn ?? "listener callback needs promotion and shell validation",
+        resumeHint: result.resumeHint ?? `Check ${snapshot.listenerId}, promote it to an active shell, then interact and stabilize it.`,
+        nextWorkerType: result.nextWorkerType ?? "shell-supervisor"
+      };
+    }
+    if (snapshot.phase === "listener_waiting" && snapshot.listenerId) {
+      return {
+        ...result,
+        status: result.status === "success" || result.status === "partial" ? "waiting" : result.status,
+        assets: uniq([...result.assets, `listener:${snapshot.listenerId}`]),
+        waitingOn: result.waitingOn ?? "incoming reverse-shell callback",
+        resumeHint: result.resumeHint ?? `Poll ${snapshot.listenerId} with bg_process status, then promote immediately if a connection appears.`,
+        nextWorkerType: result.nextWorkerType ?? "shell-supervisor"
+      };
+    }
+    return result;
+  }
+};
+
+// src/engine/agent-tool/worker-executor-factory.ts
+function createDelegatedWorkerExecutor(input) {
+  if (input.workerType === "shell-supervisor") {
+    return new ShellSupervisorWorker();
+  }
+  if (input.workerType === "exploit") {
+    return new ExploitWorker();
+  }
+  if (input.workerType === "pwn") {
+    return new PwnWorker();
+  }
+  return new DefaultDelegatedWorkerExecutor();
+}
+
+// src/engine/agent-tool/agent-tool.ts
+var TIMEOUT_RESULT = {
+  status: "failed",
+  summary: `Agent-tool timed out: max ${MAX_AGENT_TOOL_ITERATIONS} iterations reached without task_complete.`,
+  tried: [],
+  findings: [],
+  loot: [],
+  sessions: [],
+  assets: [],
+  suggestedNext: "Break the task into smaller sub-tasks and retry."
+};
+var AgentTool = class {
+  constructor(state, events, scopeGuard, approvalGate) {
+    this.state = state;
+    this.events = events;
+    this.scopeGuard = scopeGuard;
+    this.approvalGate = approvalGate;
+  }
+  async execute(input) {
+    const workerExecutor = createDelegatedWorkerExecutor(input);
+    const preparedInput = workerExecutor.prepareInput(input);
+    const completion = createCompletionBox();
+    const registry = new AgentRegistry(
+      this.state,
+      this.scopeGuard,
+      this.approvalGate,
+      this.events,
+      completion
+    );
+    const runner = new AgentRunner(
+      this.state,
+      this.events,
+      registry,
+      completion
+    );
+    const prompt = buildAgentPrompt(preparedInput, workerExecutor);
+    const loopResult = await runner.run(preparedInput.task, prompt);
+    if (completion.done && completion.result) {
+      return workerExecutor.finalizeResult(preparedInput, completion.result);
+    }
+    return {
+      ...TIMEOUT_RESULT,
+      tried: [`Reached ${loopResult.iterations} iterations without calling task_complete`]
+    };
+  }
+};
+export {
+  AgentTool
+};