@agentprojectcontext/apx 1.66.0 → 1.67.0

package/src/core/agent/security.js

@@ -0,0 +1,97 @@
+// Inline security-risk analysis (OpenHands LLMSecurityAnalyzer pattern).
+//
+// Instead of a second "is this safe?" LLM call, the model grades each of its
+// OWN tool calls by filling a `security_risk` field injected into every tool
+// schema. The agent loop extracts the field before execution and a
+// confirmation policy decides whether the call pauses for human approval.
+// Zero extra latency, zero extra tokens beyond the one enum argument.
+//
+// Risk semantics (ordered): LOW < MEDIUM < HIGH. UNKNOWN means the model
+// omitted the field (weak models do) — the policy decides whether UNKNOWN
+// pauses via `confirm_unknown`.
+
+export const SECURITY_RISK_LEVELS = Object.freeze(["LOW", "MEDIUM", "HIGH"]);
+export const SECURITY_RISK_UNKNOWN = "UNKNOWN";
+
+const RISK_ORDER = { LOW: 1, MEDIUM: 2, HIGH: 3 };
+
+// Loop-control / interaction tools that never touch the world — grading them
+// only burns tokens and trains the model to rubber-stamp the field.
+const RISK_EXEMPT_TOOLS = new Set(["finish", "ask_questions", "discover_tools"]);
+
+export function normalizeRisk(value) {
+  const v = String(value || "").trim().toUpperCase();
+  return RISK_ORDER[v] ? v : SECURITY_RISK_UNKNOWN;
+}
+
+export function securityRiskConfig(globalConfig) {
+  const raw = globalConfig?.super_agent?.security_risk || {};
+  return {
+    enabled: raw.enabled === true,
+    confirm_at: normalizeRisk(raw.confirm_at) === SECURITY_RISK_UNKNOWN ? "HIGH" : normalizeRisk(raw.confirm_at),
+    confirm_unknown: raw.confirm_unknown !== false,
+  };
+}
+
+export function isSecurityRiskEnabled(globalConfig) {
+  return securityRiskConfig(globalConfig).enabled;
+}
+
+const SECURITY_RISK_PROPERTY = Object.freeze({
+  type: "string",
+  enum: [...SECURITY_RISK_LEVELS],
+  description:
+    "Your assessment of the safety risk of this action. LOW: read-only or " +
+    "trivially reversible. MEDIUM: modifies local state but is reversible. " +
+    "HIGH: destructive, outward-facing (messages someone, publishes, spends) " +
+    "or hard to reverse.",
+});
+
+/**
+ * Return a copy of `schemas` where every eligible tool gains a required
+ * `security_risk` enum parameter. Originals are never mutated (schemas are
+ * module-level constants shared across sessions). The field is listed first
+ * so it stays visible to the model, mirroring OpenHands' field prioritization.
+ */
+export function withSecurityRiskField(schemas) {
+  return (schemas || []).map((s) => {
+    const fn = s?.function;
+    const name = fn?.name || s?.name;
+    if (!fn || !name || RISK_EXEMPT_TOOLS.has(name)) return s;
+    const params = fn.parameters || { type: "object", properties: {} };
+    if (params.properties?.security_risk) return s;
+    return {
+      ...s,
+      function: {
+        ...fn,
+        parameters: {
+          ...params,
+          properties: { security_risk: SECURITY_RISK_PROPERTY, ...(params.properties || {}) },
+          required: ["security_risk", ...(params.required || [])],
+        },
+      },
+    };
+  });
+}
+
+/**
+ * Extract (and delete) `security_risk` from parsed tool args. Handlers never
+ * see the field — it belongs to the loop, not the tool contract.
+ */
+export function popSecurityRisk(args) {
+  if (!args || typeof args !== "object") return SECURITY_RISK_UNKNOWN;
+  const risk = normalizeRisk(args.security_risk);
+  delete args.security_risk;
+  return risk;
+}
+
+/**
+ * ConfirmRisky policy: pause when the model's own grade meets the configured
+ * threshold (or when it didn't grade at all and confirm_unknown is on).
+ */
+export function shouldConfirmRisk(risk, cfg) {
+  if (!cfg?.enabled) return false;
+  const r = normalizeRisk(risk);
+  if (r === SECURITY_RISK_UNKNOWN) return cfg.confirm_unknown !== false;
+  return RISK_ORDER[r] >= RISK_ORDER[cfg.confirm_at || "HIGH"];
+}

package/src/core/agent/stuck-detector.js

@@ -0,0 +1,89 @@
+// Stuck detection (OpenHands StuckDetector pattern, adapted to the APX loop).
+//
+// Two loop shapes matter here — both invisible to the side-effect dedupe,
+// which only guards mutating tools:
+//   - action_observation: the model re-issues the SAME call and gets the SAME
+//     result N times (read_file on the same path, list_* over and over);
+//   - action_error: the SAME call keeps erroring M times in a row (auth wall,
+//     missing binary) — different error text still counts, retrying is the
+//     stuck part.
+//
+// The loop's monologue/no-tool patterns don't apply: run-agent already breaks
+// when a turn produces no tool calls.
+
+export function stuckDetectionConfig(globalConfig) {
+  const raw = globalConfig?.super_agent?.stuck_detection || {};
+  return {
+    enabled: raw.enabled !== false,
+    action_repeat:
+      Number.isFinite(raw.action_repeat) && raw.action_repeat > 1 ? raw.action_repeat : 4,
+    error_repeat:
+      Number.isFinite(raw.error_repeat) && raw.error_repeat > 1 ? raw.error_repeat : 3,
+  };
+}
+
+const WINDOW_SIZE = 20;
+
+export function createStuckDetector(cfg) {
+  const window = [];
+  return {
+    record({ tool, argsSig, resultSig, isError }) {
+      window.push({ tool, argsSig, resultSig, isError: isError === true });
+      if (window.length > WINDOW_SIZE) window.shift();
+    },
+
+    // Returns { pattern, tool, repeats } when a stuck pattern closes on the
+    // latest record, else null. Checked after every tool execution.
+    check() {
+      if (!cfg.enabled) return null;
+
+      const errs = window.slice(-cfg.error_repeat);
+      if (
+        errs.length === cfg.error_repeat &&
+        errs.every(
+          (r) => r.isError && r.tool === errs[0].tool && r.argsSig === errs[0].argsSig
+        )
+      ) {
+        return { pattern: "action_error", tool: errs[0].tool, repeats: cfg.error_repeat };
+      }
+
+      const acts = window.slice(-cfg.action_repeat);
+      if (
+        acts.length === cfg.action_repeat &&
+        acts.every(
+          (r) =>
+            r.tool === acts[0].tool &&
+            r.argsSig === acts[0].argsSig &&
+            r.resultSig === acts[0].resultSig
+        )
+      ) {
+        return { pattern: "action_observation", tool: acts[0].tool, repeats: cfg.action_repeat };
+      }
+
+      return null;
+    },
+
+    // Cleared after a nudge so old records can't instantly re-trigger — only
+    // NEW repetitions after the warning count towards the abort.
+    reset() {
+      window.length = 0;
+    },
+  };
+}
+
+// In-band note, WRAPUP_SIGNAL-style: shapes behavior only, wording stays the
+// model's. Delivered as a conversation turn because weak models reliably
+// answer the latest turn but routinely ignore system-suffix nudges.
+export function stuckNudgeSignal({ tool, repeats, pattern }) {
+  const shape =
+    pattern === "action_error"
+      ? `kept failing the same way ${repeats} times in a row`
+      : `returned the same result ${repeats} times in a row`;
+  return (
+    `[Internal turn note — this is NOT from the user. Your call to \`${tool}\` ` +
+    `${shape}. You appear to be stuck in a loop. Do NOT repeat that exact call ` +
+    "again. Either take a genuinely different approach (different tool, " +
+    "different arguments), or — if you cannot advance without help — tell the " +
+    "user plainly, in their language, what you tried and what is blocking you.]"
+  );
+}

package/src/core/agent/super-agent.js

@@ -8,10 +8,12 @@ import {
   isSuperAgentEnabled,
   buildIdentityBlock,
   loadDefaultSystemPrompt,
+  selectModelByRules,
 } from "#core/agent/index.js";
 import { resolveAgentName } from "#core/identity/index.js";
-import { memoryBlockFor } from "#core/memory/index.js";
+import { memoryBlockFor, buildActiveThreadsBlock } from "#core/memory/index.js";
 import { CHANNELS } from "#core/constants/channels.js";
+import { judgeConfig, judgeCompletion, applyJudgeLoop } from "#core/agent/judge.js";
 
 export {
   buildIdentityBlock,
@@ -70,6 +72,9 @@ export async function runSuperAgent({
   // because a per-turn skill inspector already injected the right context.
   // Set by the daemon's super-agent endpoint when config.skills.inspector is on.
   skipSkillsHint = false,
+  // Nesting depth of this run. 0 = user-facing turn; the run_subagent tool
+  // spawns children with depth+1 and refuses past its MAX_DEPTH.
+  subagentDepth = 0,
 }) {
   if (!isSuperAgentEnabled(globalConfig)) {
     throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
@@ -129,22 +134,58 @@ export async function runSuperAgent({
 
   const toolSchemas = noTools ? [] : toolSession.initialSchemas;
 
-  return runAgent({
-    globalConfig,
-    system,
-    prompt,
-    previousMessages,
-    overrideModel,
-    toolSchemas,
-    makeToolHandlers,
-    toolHandlerCtx: { projects, plugins, registries, globalConfig, channel, channelMeta, toolSession, requestConfirmation, backgroundResultSink },
+  // Content-based routing (RouterLLM pattern): rules in super_agent.routing
+  // inspect THIS turn (images, size, channel, keywords) and prefer a model for
+  // it. An explicit overrideModel always wins; the preferred model is
+  // health-checked in runAgent and falls back down the regular chain.
+  const contentRoute = overrideModel
+    ? null
+    : selectModelByRules({ prompt, previousMessages, channel, channelMeta }, globalConfig);
+
+  const runOnce = (turnPrompt, history) =>
+    runAgent({
+      globalConfig,
+      system,
+      prompt: turnPrompt,
+      previousMessages: history,
+      overrideModel,
+      preferredModel: contentRoute?.model || null,
+      toolSchemas,
+      makeToolHandlers,
+      toolHandlerCtx: { projects, plugins, registries, globalConfig, channel, channelMeta, toolSession, requestConfirmation, backgroundResultSink, subagentDepth },
+      onEvent,
+      signal,
+      onToken,
+      agentName: resolveAgentName(globalConfig),
+      suppressTools,
+      ...(maxTokens ? { maxTokens } : {}),
+      ...(maxIters ? { maxIters } : {}),
+      ...(completionContract ? { completionContract: true } : {}),
+    });
+
+  const result = await runOnce(prompt, previousMessages);
+
+  // Goal-completion judge (OpenHands critic pattern): opt-in, and only where
+  // "done" is a checkable claim — completion-contract turns at the top level.
+  // Sub-agent runs are excluded (the parent already judges the overall turn);
+  // tool-free callers (summarize/ask) have nothing to verify.
+  const jCfg = judgeConfig(globalConfig);
+  if (!jCfg.enabled || !completionContract || noTools || subagentDepth > 0) {
+    return result;
+  }
+  // Rolling refinement history: each round sees the original goal, its own
+  // prior reply, and the judge's follow-up as ordinary conversation turns.
+  const history = [...previousMessages, { role: "user", content: prompt }];
+  return applyJudgeLoop({
+    initialResult: result,
+    cfg: jCfg,
     onEvent,
-    signal,
-    onToken,
-    agentName: resolveAgentName(globalConfig),
-    suppressTools,
-    ...(maxTokens ? { maxTokens } : {}),
-    ...(maxIters ? { maxIters } : {}),
-    ...(completionContract ? { completionContract: true } : {}),
+    judgeFn: (r) => judgeCompletion({ goal: prompt, result: r, globalConfig }),
+    runFollowup: async (followup, prior) => {
+      history.push({ role: "assistant", content: prior.text || "" });
+      const next = await runOnce(followup, [...history]);
+      history.push({ role: "user", content: followup });
+      return next;
+    },
   });
 }

package/src/core/agent/tools/handlers/run-subagent.js

@@ -0,0 +1,117 @@
+// Sub-agents as a composable tool (OpenHands Task-tool pattern): the model
+// delegates a self-contained chunk of work to an ISOLATED agent run — fresh
+// conversation, same registry (minus user-interaction tools), runs to
+// completion, and the final text comes back as this tool's observation.
+import { TOOLS } from "../names.js";
+
+// One level of nesting only: a sub-agent cannot spawn another sub-agent.
+// Enough for delegation, and it hard-bounds the fan-out a confused model can
+// create (depth 2 with a loop would be exponential).
+const MAX_DEPTH = 1;
+const DEFAULT_MAX_ITERS = 16;
+const MAX_MAX_ITERS = 24;
+
+// Withheld from the child: it has no path to the user (the parent relays), so
+// user-interaction tools would either dead-end (ask_questions) or bypass the
+// parent's narrative (send_telegram). run_subagent itself enforces MAX_DEPTH
+// twice — suppression here, depth check in the handler.
+const CHILD_SUPPRESSED_TOOLS = [
+  TOOLS.RUN_SUBAGENT,
+  TOOLS.ASK_QUESTIONS,
+  TOOLS.SEND_TELEGRAM,
+];
+
+export default {
+  name: "run_subagent",
+
+  schema: {
+    type: "function",
+    function: {
+      name: "run_subagent",
+      description:
+        "Spawn an isolated sub-agent for a self-contained task and return its " +
+        "result. The sub-agent starts with a FRESH context (it does not see " +
+        "this conversation), gets the regular tool registry minus " +
+        "user-interaction tools, works until done and hands back its final " +
+        "answer. Use it to delegate a bounded chunk of work (research a " +
+        "question, refactor a file, produce a summary) while you keep the main " +
+        "thread. The prompt MUST be self-contained: include file paths, " +
+        "constraints and every piece of context the sub-agent needs.",
+      parameters: {
+        type: "object",
+        properties: {
+          prompt: {
+            type: "string",
+            description: "Full, self-contained task for the sub-agent.",
+          },
+          description: {
+            type: "string",
+            description: "Short (3-5 word) label for the task.",
+          },
+          max_iters: {
+            type: "integer",
+            description: `Optional tool-step budget (default ${DEFAULT_MAX_ITERS}, max ${MAX_MAX_ITERS}).`,
+          },
+        },
+        required: ["prompt"],
+      },
+    },
+  },
+
+  makeHandler: (ctx) => async ({ prompt, description, max_iters } = {}) => {
+    if (!prompt || !String(prompt).trim()) {
+      return { error: "run_subagent: prompt is required" };
+    }
+    const depth = Number(ctx.subagentDepth) || 0;
+    if (depth >= MAX_DEPTH) {
+      return {
+        error:
+          "run_subagent: nesting limit reached — a sub-agent cannot spawn another sub-agent. Do the work directly.",
+      };
+    }
+
+    // Dynamic import: registry → this handler → super-agent → registry would
+    // otherwise be a static ESM cycle.
+    const { runSuperAgent } = await import("#core/agent/super-agent.js");
+
+    const parsed = parseInt(max_iters, 10);
+    const maxIters = Math.min(
+      Math.max(Number.isFinite(parsed) ? parsed : DEFAULT_MAX_ITERS, 2),
+      MAX_MAX_ITERS
+    );
+
+    const started = Date.now();
+    try {
+      const result = await runSuperAgent({
+        globalConfig: ctx.globalConfig,
+        projects: ctx.projects,
+        plugins: ctx.plugins,
+        registries: ctx.registries,
+        prompt: String(prompt),
+        channel: ctx.channel,
+        channelMeta: ctx.channelMeta,
+        previousMessages: [],
+        // Confirmations still reach the human: the child inherits the parent's
+        // channel adapter, so a risky child action pauses the same dialog.
+        requestConfirmation: ctx.requestConfirmation || null,
+        suppressTools: CHILD_SUPPRESSED_TOOLS,
+        maxIters,
+        // Delegation semantics: the child works until it declares done via
+        // `finish` — it can't end its run by narrating the next step.
+        completionContract: true,
+        subagentDepth: depth + 1,
+      });
+      return {
+        ok: true,
+        ...(description ? { description } : {}),
+        text: result.text || "",
+        steps: Array.isArray(result.trace) ? result.trace.length : 0,
+        model: result.model,
+        usage: result.usage,
+        duration_ms: Date.now() - started,
+      };
+    } catch (e) {
+      return { error: `run_subagent failed: ${e.message}` };
+    }
+  },
+};

package/src/core/agent/tools/helpers.js

@@ -38,6 +38,13 @@ export function buildAgentSystem(project, agent, opts = {}) {
 
 export function createPermissionGuard(globalConfig = {}, {
   requestConfirmation = null,
+  // Inline security-risk gate handshake (see run-agent.js). A callable that
+  // returns `{active, cleared}` for the tool call currently executing:
+  //   active  — the risk analyzer owns dangerous-call gating this session, so
+  //             the static dangerous-flag branch of "automatico" stands down.
+  //   cleared — the user already approved THIS call at the risk gate; asking
+  //             again here would double-prompt.
+  securityGate = null,
 } = {}) {
   const permissionMode = globalConfig.super_agent?.permission_mode || DEFAULT_PERMISSION_MODE;
   const allowedTools = new Set(globalConfig.super_agent?.allowed_tools || []);
@@ -49,9 +56,12 @@ export function createPermissionGuard(globalConfig = {}, {
   return async function requirePermission(tool, { dangerous = false, args } = {}) {
     if (permissionMode === PERMISSION_MODES.TOTAL) return;
 
+    const gate = typeof securityGate === "function" ? securityGate() : null;
+    if (gate?.cleared) return;
+
     const blocked =
       (permissionMode === PERMISSION_MODES.PERMISO && !allowedTools.has(tool)) ||
-      (permissionMode === PERMISSION_MODES.AUTOMATICO && dangerous);
+      (permissionMode === PERMISSION_MODES.AUTOMATICO && dangerous && !gate?.active);
 
     if (!blocked) return;
 

package/src/core/agent/tools/names.js

@@ -49,6 +49,7 @@ export const TOOLS = Object.freeze({
   CALL_AGENT:          "call_agent",
   CALL_MCP:            "call_mcp",
   CALL_RUNTIME:        "call_runtime",
+  RUN_SUBAGENT:        "run_subagent",
 
   // Integrations — Asana plugin (see core/integrations/plugins/asana.js)
   ASANA_LIST_PROJECTS: "asana_list_projects",
@@ -104,6 +105,7 @@ export const NATIVE_TOOL_NAMES = new Set([
   TOOLS.CALL_AGENT,
   TOOLS.CALL_MCP,
   TOOLS.CALL_RUNTIME,
+  TOOLS.RUN_SUBAGENT,
   TOOLS.ASANA_LIST_PROJECTS,
   TOOLS.ASANA_LIST_TASKS,
   TOOLS.ASANA_CREATE_TASK,

package/src/core/agent/tools/registry.js

@@ -18,6 +18,7 @@ import searchSessions from "./handlers/search-sessions.js";
 import callAgent from "./handlers/call-agent.js";
 import callMcp from "./handlers/call-mcp.js";
 import callRuntime from "./handlers/call-runtime.js";
+import runSubagent from "./handlers/run-subagent.js";
 import sendTelegram from "./handlers/send-telegram.js";
 import setIdentity from "./handlers/set-identity.js";
 import setPermissionMode from "./handlers/set-permission-mode.js";
@@ -65,6 +66,7 @@ const NATIVE_TOOLS = [
   callAgent,
   callMcp,
   callRuntime,
+  runSubagent,
   sendTelegram,
   setIdentity,
   setPermissionMode,
@@ -184,6 +186,7 @@ const NATIVE_CATEGORY = {
   [TOOLS.IMPORT_AGENT]:        "agents",
   [TOOLS.ADD_PROJECT]:         "projects",
   [TOOLS.CALL_AGENT]:          "agents",
+  [TOOLS.RUN_SUBAGENT]:        "agents",
   [TOOLS.CALL_RUNTIME]:        "runtime",
   [TOOLS.CALL_MCP]:            "mcp",
   [TOOLS.READ_AGENT_MEMORY]:   "memory",
@@ -384,6 +387,13 @@ export function makeToolHandlers(ctx) {
     ...ctx,
     requirePermission: createPermissionGuard(ctx.globalConfig || {}, {
       requestConfirmation: ctx.requestConfirmation || null,
+      // Live view of the risk-gate state for the CURRENT tool call. Reads the
+      // original ctx object (not the spread copy) because run-agent.js mutates
+      // it per call — see the security-risk section of the loop.
+      securityGate: () => ({
+        active: ctx.securityRiskActive === true,
+        cleared: ctx.securityGateCleared === true,
+      }),
     }),
   };
   return Object.fromEntries(ALL_TOOLS.map((tool) => [tool.name, tool.makeHandler(toolCtx)]));