@xiangyixie/dsh-superagent 0.14.3 → 0.14.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.js CHANGED
@@ -10,7 +10,7 @@
10
10
  * Registered tools: superagent_start, superagent_status, superagent_list,
11
11
  * superagent_cancel, superagent_resume, superagent_followup, superagent_inject,
12
12
  * superagent_answer, superagent_memory, superagent_template, superagent_audit,
13
- * superagent_schedule.
13
+ * superagent_schedule, superagent_goal.
14
14
  *
15
15
  * @module dsh-superagent
16
16
  */
@@ -36,6 +36,7 @@ import { createUserMemory, USER_MEMORY_CATEGORIES } from './user-memory.js'
36
36
  import { createNotifyPolicy, createOutbox } from './notify.js'
37
37
  import { createRuntimeControl } from './runtime-control.js'
38
38
  import { createScheduler, formatSchedule, formatScheduleList } from './schedule.js'
39
+ import { createLongGoalManager, formatStatus as formatLongGoal } from './long-goal.js'
39
40
  import { ACTIVE_STATUSES, createStore, resolveStateRoot, TERMINAL_STATUSES } from './store.js'
40
41
  import { createTemplateStore, expandTemplate, formatTemplateDetail, formatTemplateList, TemplateError } from './templates.js'
41
42
  import { createUsageReader } from './usage.js'
@@ -47,7 +48,7 @@ import { createBoard } from './board.js'
47
48
 
48
49
  export const name = 'dsh-superagent'
49
50
  // The host menu and sessions are required. `subagents` is read through
50
- // `ctx.get('subagents')`, so a profile without it still mounts the twelve tools;
51
+ // `ctx.get('subagents')`, so a profile without it still mounts the thirteen tools;
51
52
  // they then report what is missing instead of the plugin silently vanishing.
52
53
  export const inject = ['tools', 'agents']
53
54
 
@@ -1254,16 +1255,19 @@ export function apply(ctx, config) {
1254
1255
  // `superagent_start` next to the host's `subagent` tool can hand-orchestrate
1255
1256
  // the work with the latter — three children, three report fragments, and no
1256
1257
  // run, no plan, no merged report, and nothing in the run list to look at.
1257
- // This nudge is the only thing that states the policy, so it is injected
1258
- // once per turn, at the first step of a top-level session.
1258
+ // This nudge is the only thing that states the policy, so it is injected once
1259
+ // per session, at the first step of a top-level session: repeating it every
1260
+ // turn would put another copy in the history each time.
1259
1261
  const GUIDANCE_SOURCE = { kind: 'superagent-guidance', form: 'notice', summary: '多步目标先起 run' }
1260
1262
  const GUIDANCE_TEXT = [
1261
- '多步目标必须先用 superagent_start(mode="planned") 起一个 run:目标含两个及以上可独立交付物,',
1262
- '或含“先做 A 才能做 B”的前置依赖时都算多步。之后用 superagent_followup 续,用 superagent_status 读报告。',
1263
- '不要用宿主内置的 subagent 工具自己编排这些子任务——那样没有 run 记录、没有计划、没有合并报告。',
1264
- '直接调用 superagent_start,不要先判断“当前有没有这个工具”;只有调用返回工具不存在时,才退回 subagent 并说明原因。',
1265
- '只有单一动作(一次查找、一次编辑、一条命令、一段短文本)才直接做,不必起 run。',
1263
+ '多步目标(两个及以上可独立交付物,或含“先 A 后 B”的前置依赖)先用 superagent_start(mode="planned") 起 run,',
1264
+ '之后用 superagent_followup 续、superagent_status 读报告;不要用内置 subagent 自己编排,那样没有计划与合并报告。',
1265
+ '直接调用,先不要确认工具是否存在;只有返回不存在时才退回 subagent。单一动作直接做,不必起 run。',
1266
+ '长期目标、定时、跨 run 记忆、模板、审计、实时插话:先调 superagent_help 展开这些工具。',
1266
1267
  ].join('')
1268
+ // Session ids that already carry the notice in their history. Bounded so a
1269
+ // long-lived host cannot accumulate them without limit.
1270
+ const guidedSessions = new Set()
1267
1271
  if (typeof ctx.on === 'function') {
1268
1272
  ctx.on('agent/pre-step', async ({ agent, step }, next) => {
1269
1273
  const decision = await next()
@@ -1272,6 +1276,12 @@ export function apply(ctx, config) {
1272
1276
  if (!header) return decision
1273
1277
  if ((header.delegationDepth ?? 0) > 0 || header.origin === 'subagent') return decision
1274
1278
  if (decision.messages.some(message => message?.source?.kind === GUIDANCE_SOURCE.kind)) return decision
1279
+ const sessionId = sessionKey(agent)
1280
+ if (sessionId && guidedSessions.has(sessionId)) return decision
1281
+ if (sessionId) {
1282
+ if (guidedSessions.size >= 2000) guidedSessions.clear()
1283
+ guidedSessions.add(sessionId)
1284
+ }
1275
1285
  const guidance = {
1276
1286
  id: randomUUID(),
1277
1287
  role: 'user',
@@ -1282,6 +1292,20 @@ export function apply(ctx, config) {
1282
1292
  })
1283
1293
  }
1284
1294
 
1295
+ // Every declaration is paid for on every request, so the capabilities most
1296
+ // sessions never touch are registered with a per-session activation
1297
+ // condition (see EXTRA_TOOLS): `superagent_help` names them and turns them on.
1298
+ const expandedSessions = new Set()
1299
+ const sessionKey = agent => {
1300
+ const header = agent?.session?.header
1301
+ return agent?.id ?? header?.id ?? header?.sessionId
1302
+ }
1303
+ const isExpanded = agent => Boolean(expandedSessions.has(sessionKey(agent)))
1304
+ // The host's contract is `tools.register(definition, { when })`: `when` is
1305
+ // evaluated for every step, and false keeps the tool out of that step's
1306
+ // declarations and dispatch.
1307
+ const EXTRA_TOOLS = { when: context => isExpanded(context?.agent) }
1308
+
1285
1309
  // Runtime control is opt-in. With `runtime.enabled` false nothing below is
1286
1310
  // registered, which is why a profile that never asked for browser or desktop
1287
1311
  // access sees exactly the same tool list as before this layer existed.
@@ -1316,7 +1340,7 @@ export function apply(ctx, config) {
1316
1340
  /**
1317
1341
  * The subagent service is optional, so it is read from the service store at
1318
1342
  * call time rather than declared as an injection: a profile without it must
1319
- * still mount the twelve tools (they then explain what is missing), and reading
1343
+ * still mount the thirteen tools (they then explain what is missing), and reading
1320
1344
  * it lazily also sees a service that registers after this plugin.
1321
1345
  */
1322
1346
  function getSubagents() {
@@ -1722,8 +1746,27 @@ export function apply(ctx, config) {
1722
1746
  * @param {object} plan - plan whose window is firing.
1723
1747
  * @returns {Promise<object | {agent: object, sessionId: string} | null>} agent or agent+id.
1724
1748
  */
1725
- async function recoverScheduleOwner(plan) {
1749
+ async function recoverScheduleOwner(plan, label = 'schedule', options = {}) {
1726
1750
  const agents = getAgents()
1751
+ const session = getSessionController()
1752
+ // `agents.resume` reopens the transcript without the Session's agent
1753
+ // preset, so the agent it returns runs without the file and shell tools the
1754
+ // Session was created with. A long-goal phase hands its owner to child
1755
+ // agents, so it needs a fully composed owner: the session controller mounts
1756
+ // the recorded preset, which is why the goal path asks it first. Scheduled
1757
+ // runs keep the old order so their behaviour does not change.
1758
+ if (options.preferResolve && session && typeof session.resolveAgent === 'function') {
1759
+ try {
1760
+ const resolved = await session.resolveAgent(plan.ownerSessionId)
1761
+ if (resolved?.agent) {
1762
+ const registered = getAgents()?.get?.(plan.ownerSessionId)
1763
+ return registered ?? resolved.agent
1764
+ }
1765
+ if (resolved?.error) log(`${label} ${plan.id}: cannot open session ${plan.ownerSessionId}: ${resolved.error}`)
1766
+ } catch (error) {
1767
+ log(`${label} ${plan.id}: cannot open session ${plan.ownerSessionId}: ${error?.message ?? error}`)
1768
+ }
1769
+ }
1727
1770
  if (agents && typeof agents.resume === 'function') {
1728
1771
  try {
1729
1772
  const handle = await agents.resume({ resumeSessionId: plan.ownerSessionId })
@@ -1732,17 +1775,16 @@ export function apply(ctx, config) {
1732
1775
  return handle.agent
1733
1776
  }
1734
1777
  } catch (error) {
1735
- log(`schedule ${plan.id}: cannot resume session ${plan.ownerSessionId}: ${error?.message ?? error}`)
1778
+ log(`${label} ${plan.id}: cannot resume session ${plan.ownerSessionId}: ${error?.message ?? error}`)
1736
1779
  }
1737
1780
  }
1738
- const session = getSessionController()
1739
1781
  if (session && typeof session.resolveAgent === 'function') {
1740
1782
  const resolved = await session.resolveAgent(plan.ownerSessionId)
1741
1783
  if (resolved?.agent) {
1742
1784
  const registered = getAgents()?.get?.(plan.ownerSessionId)
1743
1785
  return registered ?? resolved.agent
1744
1786
  }
1745
- if (resolved?.error) log(`schedule ${plan.id}: cannot resume session ${plan.ownerSessionId}: ${resolved.error}`)
1787
+ if (resolved?.error) log(`${label} ${plan.id}: cannot resume session ${plan.ownerSessionId}: ${resolved.error}`)
1746
1788
  }
1747
1789
  if (agents && typeof agents.create === 'function') {
1748
1790
  const sessionId = randomUUID()
@@ -1756,7 +1798,7 @@ export function apply(ctx, config) {
1756
1798
  return { agent: handle.agent, sessionId }
1757
1799
  }
1758
1800
  } catch (error) {
1759
- log(`schedule ${plan.id}: cannot create a replacement session: ${error?.message ?? error}`)
1801
+ log(`${label} ${plan.id}: cannot create a replacement session: ${error?.message ?? error}`)
1760
1802
  }
1761
1803
  }
1762
1804
  if (session && typeof session.create === 'function') {
@@ -1770,7 +1812,7 @@ export function apply(ctx, config) {
1770
1812
  if (resolved?.agent) return { agent: resolved.agent, sessionId }
1771
1813
  }
1772
1814
  }
1773
- log(`schedule ${plan.id}: the host could not create a replacement session`)
1815
+ log(`${label} ${plan.id}: the host could not create a replacement session`)
1774
1816
  }
1775
1817
  return null
1776
1818
  }
@@ -1817,6 +1859,54 @@ export function apply(ctx, config) {
1817
1859
  warn: log,
1818
1860
  })
1819
1861
 
1862
+ // A long-term goal is a thin layer above runs: each phase is a normal run.
1863
+ // The manager only owns the phase graph, the goal budget, and the decisions
1864
+ // that a phase cannot make by itself. Keeping it behind the orchestrator API
1865
+ // means it inherits every run-side guarantee (locks, persistence, resume).
1866
+ const longGoal = createLongGoalManager({
1867
+ root: store.root,
1868
+ orchestrator: {
1869
+ start: args => orchestrator.start(args),
1870
+ status: runId => orchestrator.status(runId),
1871
+ resume: (runId, parent, clientTimeZone) => orchestrator.resume(runId, parent, clientTimeZone),
1872
+ cancel: runId => orchestrator.cancel(runId),
1873
+ answer: (runId, attentionId, answer, agent, clientTimeZone) =>
1874
+ orchestrator.answer(runId, attentionId, answer, agent, clientTimeZone),
1875
+ },
1876
+ async resolveOwner(goal) {
1877
+ const live = getAgents()?.get?.(goal.ownerSessionId)
1878
+ if (live && typeof live === 'object') return live
1879
+ return recoverScheduleOwner(goal, 'long-goal', { preferResolve: true })
1880
+ },
1881
+ async notify({ goal, message }) {
1882
+ let agent = getAgents()?.get?.(goal.ownerSessionId)
1883
+ if (!agent) {
1884
+ const recovered = await recoverScheduleOwner(goal, 'long-goal', { preferResolve: true })
1885
+ agent = recovered?.agent ?? recovered ?? null
1886
+ }
1887
+ if (!agent || typeof agent.followup !== 'function') {
1888
+ log(`long-goal ${goal.id} has no live session ${goal.ownerSessionId} to notify`)
1889
+ return { delivered: false }
1890
+ }
1891
+ await outbox.enqueue(goal.ownerSessionId, () => agent.followup({
1892
+ id: randomUUID(),
1893
+ role: 'user',
1894
+ content: [{ type: 'text', text: message }],
1895
+ source: { kind: 'user' },
1896
+ }))
1897
+ return { delivered: true }
1898
+ },
1899
+ config: {
1900
+ phaseBudget: {
1901
+ maxModelCalls: cfg.maxModelCallsPerRun,
1902
+ maxTokens: cfg.maxTokensPerRun,
1903
+ },
1904
+ },
1905
+ log,
1906
+ now: () => Date.now(),
1907
+ tickSeconds: 5,
1908
+ })
1909
+
1820
1910
  // Recovery runs once at mount; tools wait for it so a run left active by a
1821
1911
  // dead host reads as interrupted before the first tool call sees it. A
1822
1912
  // failure to initialize the state directory is kept and reported by every
@@ -1859,6 +1949,15 @@ export function apply(ctx, config) {
1859
1949
  } catch (error) {
1860
1950
  log(`cannot load scheduled runs from ${scheduler.stateFile}: ${error?.message ?? error}`)
1861
1951
  }
1952
+ // Long goals survive the host on their own: init marks the phases that were
1953
+ // mid-run as resumable and the manager continues them on its next tick.
1954
+ try {
1955
+ const goals = await longGoal.init()
1956
+ const active = goals.filter(item => ['planning', 'running', 'paused'].includes(item.status)).length
1957
+ if (goals.length > 0) log(`long goals: ${goals.length} loaded, ${active} to continue`)
1958
+ } catch (error) {
1959
+ log(`cannot load long goals: ${error?.message ?? error}`)
1960
+ }
1862
1961
  if (!(cfg.keepRuns > 0) || typeof store.prune !== 'function') return
1863
1962
  try {
1864
1963
  const { removed } = await store.prune({ olderThanDays: cfg.keepRuns })
@@ -1929,61 +2028,43 @@ export function apply(ctx, config) {
1929
2028
  ctx.tools.register(defineTool({
1930
2029
  name: 'superagent_start',
1931
2030
  description:
1932
- 'Start a long-horizon autonomous run: a planner decomposes the goal into subtasks, '
1933
- + 'independent subtasks run in parallel child agents while ones with a declared dependency wait for it, '
1934
- + 'and their reports are merged into one final report. '
1935
- + 'Pass mode "direct" for a single self-contained task instead: one worker does it, there is no planner '
1936
- + 'or aggregator, and its reply is the report verbatim — use it for one lookup, one edit, one query, or '
1937
- + 'one short piece of writing, not for a goal with parts that can be worked in parallel. '
1938
- + 'Prefer this over the built-in subagent tool whenever the goal has several deliverables or a '
1939
- + 'declared prerequisite step: only a run keeps the plan, the parallel timing, and one merged report. '
1940
- + 'The call returns immediately with a run id; poll it with superagent_status. Runs are persisted, '
1941
- + 'so they survive a host restart and can be resumed or cancelled.',
2031
+ 'Start an autonomous run: a planner splits the goal into subtasks, independent ones run in parallel, and their '
2032
+ + 'reports merge into one. Use it instead of the host subagent tool for goals with several deliverables or an '
2033
+ + 'ordered prerequisite. Returns a run id; poll with superagent_status or pass wait_seconds. '
2034
+ + 'mode "direct" runs one worker with no plan or merge.',
1942
2035
  properties: {
1943
- goal: { type: 'string', description: 'The complete goal for the run. Be specific about the expected outcome.' },
2036
+ goal: { type: 'string', description: 'The complete goal; be specific about the expected outcome.' },
1944
2037
  mode: {
1945
2038
  type: 'string',
1946
2039
  enum: ['planned', 'direct'],
1947
- description: 'planned (default): planner, parallel workers, merged report. direct: one worker runs the whole '
1948
- + 'goal, with no planning or aggregation, and its reply is returned unchanged. Choose direct only when the '
1949
- + 'task is one self-contained pass that gains nothing from splitting.',
2040
+ description: 'planned (default): plan, parallel workers, merged report. direct: one worker, reply as-is.',
1950
2041
  },
1951
2042
  queue: {
1952
2043
  type: 'boolean',
1953
- description: 'When maxActiveRuns is already in use, wait for a free slot instead of failing. The run returns '
1954
- + `status "queued" with its position, starts automatically when another run finishes, and gives up after `
1955
- + `queueTimeoutMinutes (default ${DEFAULTS.queueTimeoutMinutes}). Off by default; at most maxQueuedRuns `
1956
- + `(default ${DEFAULTS.maxQueuedRuns}) may wait.`,
2044
+ description: 'Wait for a free slot when the concurrency cap is reached, instead of failing.',
1957
2045
  },
1958
2046
  goal_mode: {
1959
2047
  type: 'boolean',
1960
- description: 'Opt in to goal mode (default false). The run does not finish when its subtasks do: an independent '
1961
- + 'acceptance step checks the acceptance conditions, and a failed round starts another one with what is '
1962
- + 'missing instead of repeating the same work. It stops when the goal is met, when max_rounds, '
1963
- + 'max_wall_clock_minutes or the budget is reached, or when consecutive rounds stop making progress. Off by '
1964
- + 'default, so a start without this flag behaves exactly as before.',
2048
+ description: 'Check acceptance conditions and start another round with what is missing until they hold.',
1965
2049
  },
1966
2050
  acceptance: {
1967
2051
  type: 'array',
1968
- description: 'Acceptance conditions, required when goal_mode is true. Each item is {id?, text, check?}. A '
1969
- + 'check is {"type":"command","command":"npm test"} (real exit code) or {"type":"file","path":"dist/app.js"} '
1970
- + '(existence); the plugin runs it, so the verdict is not the model\'s opinion. A condition without a check '
1971
- + 'is judged by an independent acceptance model, and status names the source of every verdict.',
2052
+ description: 'Required with goal_mode: conditions that decide whether the goal is met.',
1972
2053
  items: {
1973
2054
  type: 'object',
1974
2055
  properties: {
1975
- id: { type: 'string', description: 'Short id used in reports and feedback, e.g. "tests".' },
1976
- text: { type: 'string', description: 'What must hold, in one sentence.' },
2056
+ id: { type: 'string', description: 'Short id used in reports.' },
2057
+ text: { type: 'string', description: 'What must hold.' },
1977
2058
  check: {
1978
2059
  type: 'object',
1979
- description: 'Machine-checkable part; omit to have the acceptance model judge the condition.',
2060
+ description: 'Machine check; omit to let an independent model judge it.',
1980
2061
  properties: {
1981
2062
  type: { type: 'string', enum: ['command', 'file'] },
1982
- command: { type: 'string', description: 'Shell command for type "command"; its exit code is the verdict.' },
1983
- cwd: { type: 'string', description: 'Optional working directory, relative to the goal workspace.' },
2063
+ command: { type: 'string', description: 'Shell command; exit code is the verdict.' },
2064
+ cwd: { type: 'string', description: 'Working directory, relative to the goal workspace.' },
1984
2065
  timeout_seconds: { type: 'number', description: 'Command timeout (default 120, max 900).' },
1985
- path: { type: 'string', description: 'File path for type "file", relative to the goal workspace.' },
1986
- must_exist: { type: 'boolean', description: 'For type "file": true (default) requires it, false requires absence.' },
2066
+ path: { type: 'string', description: 'File path, relative to the goal workspace.' },
2067
+ must_exist: { type: 'boolean', description: 'true (default) requires the file, false its absence.' },
1987
2068
  },
1988
2069
  required: ['type'],
1989
2070
  },
@@ -1991,38 +2072,32 @@ export function apply(ctx, config) {
1991
2072
  required: ['text'],
1992
2073
  },
1993
2074
  },
1994
- max_rounds: { type: 'number', description: 'Goal mode: rounds allowed before it stops (default 5, max 20).' },
1995
- max_wall_clock_minutes: {
1996
- type: 'number',
1997
- description: 'Goal mode: wall-clock budget for the rounds (default 60; a resume restarts it).',
1998
- },
2075
+ max_rounds: { type: 'number', description: 'Goal mode: rounds before stopping (default 5, max 20).' },
2076
+ max_wall_clock_minutes: { type: 'number', description: 'Goal mode: wall-clock budget (default 60).' },
1999
2077
  no_progress_rounds: {
2000
2078
  type: 'number',
2001
- description: 'Goal mode: consecutive rounds with the same failing condition before it stops (default 2). When '
2002
- + 'the acceptance has a machine check, a round that changed no file stops immediately instead.',
2079
+ description: 'Goal mode: identical failing rounds before stopping (default 2).',
2003
2080
  },
2004
2081
  budget: {
2005
2082
  type: 'object',
2006
- description: 'Goal mode budget, narrowing the operator cap: {max_model_calls, max_tokens}.',
2083
+ description: 'Goal mode budget, inside the operator cap.',
2007
2084
  properties: {
2008
2085
  max_model_calls: { type: 'number' },
2009
2086
  max_tokens: { type: 'number' },
2010
2087
  },
2011
2088
  },
2012
- max_subtasks: { type: 'number', description: `Cap on planned subtasks (default ${DEFAULTS.maxSubtasks}, max 16).` },
2013
- max_parallel: { type: 'number', description: `Subtasks allowed to run at once (default ${DEFAULTS.maxParallel}, max 8).` },
2089
+ max_subtasks: { type: 'number', description: `Planned subtasks cap (default ${DEFAULTS.maxSubtasks}, max 16).` },
2090
+ max_parallel: { type: 'number', description: `Subtasks at once (default ${DEFAULTS.maxParallel}, max 8).` },
2014
2091
  deadline_minutes: { type: 'number', description: `Wall-clock budget in minutes (default ${DEFAULTS.deadlineMinutes}).` },
2015
2092
  allow_duplicate: {
2016
2093
  type: 'boolean',
2017
- description: 'Start a second run for the same goal even when an active run already has it. '
2018
- + 'By default the active run id is returned instead, so a retry cannot double the spend.',
2094
+ description: 'Start a second run for the same goal; default returns the active run id instead.',
2019
2095
  },
2020
2096
  approve_policy: {
2021
2097
  type: 'boolean',
2022
- description: 'Release a start that the permission policy holds for confirmation. The approval is '
2023
- + 'recorded in the audit trail. It cannot override a policy that denies the start.',
2098
+ description: 'Release a start the permission policy holds for confirmation; it cannot override a deny.',
2024
2099
  },
2025
- wait_seconds: { type: 'number', description: 'Block up to this many seconds for a terminal status before returning (0 returns immediately).' },
2100
+ wait_seconds: { type: 'number', description: 'Block up to this long for a terminal status (default 0).' },
2026
2101
  },
2027
2102
  required: ['goal'],
2028
2103
  async execute(args = {}, exec) {
@@ -2076,6 +2151,203 @@ export function apply(ctx, config) {
2076
2151
  },
2077
2152
  }))
2078
2153
 
2154
+ ctx.tools.register(defineTool({
2155
+ name: 'superagent_goal',
2156
+ description:
2157
+ 'Run a long-term goal as ordered phases: each phase is its own run with planner and parallel workers, and later '
2158
+ + 'phases receive earlier reports. A phase that keeps failing opens a decision a person answers with action '
2159
+ + '"answer". Use it over superagent_start when milestones must happen in order over a long horizon.',
2160
+ properties: {
2161
+ action: {
2162
+ type: 'string',
2163
+ enum: ['create', 'status', 'list', 'answer', 'resume', 'pause', 'cancel'],
2164
+ description: 'create, read one, list, answer an open decision, resume/pause/cancel.',
2165
+ },
2166
+ goal_id: { type: 'string', description: 'From action=create; required except for create/list.' },
2167
+ goal: {
2168
+ type: 'string',
2169
+ description: 'create: the complete long-term outcome, concrete about the finished state.',
2170
+ },
2171
+ phases: {
2172
+ type: 'array',
2173
+ description: 'create: explicit phases; omit to let the phase planner split the goal.',
2174
+ items: {
2175
+ type: 'object',
2176
+ properties: {
2177
+ id: { type: 'string', description: 'Short id, e.g. "p1"; referenced by depends_on.' },
2178
+ title: { type: 'string', description: 'Short name shown in the phase table.' },
2179
+ objective: { type: 'string', description: 'What this phase must produce.' },
2180
+ depends_on: {
2181
+ type: 'array',
2182
+ items: { type: 'string' },
2183
+ description: 'Phase ids that must complete first; omit for independent phases.',
2184
+ },
2185
+ acceptance: {
2186
+ type: 'array',
2187
+ items: {
2188
+ type: 'object',
2189
+ properties: {
2190
+ id: { type: 'string' },
2191
+ text: { type: 'string' },
2192
+ check: {
2193
+ type: 'object',
2194
+ properties: {
2195
+ type: { type: 'string', enum: ['command', 'file'] },
2196
+ command: { type: 'string' },
2197
+ cwd: { type: 'string' },
2198
+ timeout_seconds: { type: 'number' },
2199
+ path: { type: 'string' },
2200
+ must_exist: { type: 'boolean' },
2201
+ },
2202
+ required: ['type'],
2203
+ },
2204
+ },
2205
+ required: ['text'],
2206
+ },
2207
+ },
2208
+ max_rounds: { type: 'number', description: 'Retries before the phase stops (default 3).' },
2209
+ max_wall_clock_minutes: { type: 'number', description: 'Wall-clock cap (default 120).' },
2210
+ deliverables: { type: 'array', items: { type: 'string' }, description: 'Paths to report.' },
2211
+ },
2212
+ required: ['objective'],
2213
+ },
2214
+ },
2215
+ cwd: { type: 'string', description: 'Workspace for every phase and machine check (default cwd).' },
2216
+ max_parallel_phases: { type: 'number', description: 'Phases in flight at once (default 2, max 8).' },
2217
+ max_attempts_per_phase: {
2218
+ type: 'number',
2219
+ description: 'Attempts per phase before asking a person (default 2).',
2220
+ },
2221
+ max_rounds_per_phase: { type: 'number', description: 'Default goal-mode rounds per phase (default 3).' },
2222
+ no_progress_rounds: { type: 'number', description: 'Identical failing rounds before a phase stops (default 2).' },
2223
+ phase_budget: {
2224
+ type: 'object',
2225
+ description: 'Per-phase hard cap, inside what remains of the goal budget.',
2226
+ properties: {
2227
+ max_model_calls: { type: 'number' },
2228
+ max_tokens: { type: 'number' },
2229
+ },
2230
+ },
2231
+ budget: {
2232
+ type: 'object',
2233
+ description: 'Whole-goal hard cap; reaching it stops the goal.',
2234
+ properties: {
2235
+ max_model_calls: { type: 'number' },
2236
+ max_tokens: { type: 'number' },
2237
+ },
2238
+ },
2239
+ max_wall_clock_minutes: { type: 'number', description: 'Whole-goal wall-clock cap (default 1440).' },
2240
+ stall_after_minutes: {
2241
+ type: 'number',
2242
+ description: 'No completed phase for this long opens a stall decision (default 180).',
2243
+ },
2244
+ auto_resume: {
2245
+ type: 'boolean',
2246
+ description: 'Continue after a host restart (default true); false leaves it paused.',
2247
+ },
2248
+ decision_id: { type: 'string', description: 'answer: id shown in action=status.' },
2249
+ answer: {
2250
+ type: 'string',
2251
+ description: 'answer: retry, skip, stop, continue, or answer (worker question, needs note).',
2252
+ },
2253
+ note: {
2254
+ type: 'string',
2255
+ description: 'answer: new instruction for retry, or the text for a worker question.',
2256
+ },
2257
+ limit: { type: 'number', description: 'list: maximum rows (default 20).' },
2258
+ },
2259
+ required: ['action'],
2260
+ async execute(args = {}, exec) {
2261
+ const check = requireAgent(exec)
2262
+ if (check.error) return check.error
2263
+ try {
2264
+ await ready
2265
+ if (stateError) return describeError(stateError)
2266
+ const action = String(args.action ?? '').trim().toLowerCase()
2267
+ if (action === 'create') {
2268
+ const phases = Array.isArray(args.phases)
2269
+ ? args.phases.map(entry => ({
2270
+ id: entry?.id,
2271
+ title: entry?.title,
2272
+ objective: entry?.objective,
2273
+ dependsOn: entry?.depends_on ?? entry?.dependsOn,
2274
+ acceptance: Array.isArray(entry?.acceptance)
2275
+ ? entry.acceptance.map(acceptanceFromToolArgs)
2276
+ : entry?.acceptance,
2277
+ maxRounds: entry?.max_rounds ?? entry?.maxRounds,
2278
+ maxWallClockMinutes: entry?.max_wall_clock_minutes ?? entry?.maxWallClockMinutes,
2279
+ deliverables: entry?.deliverables,
2280
+ }))
2281
+ : undefined
2282
+ const created = await longGoal.create({
2283
+ goal: args.goal,
2284
+ phases,
2285
+ cwd: args.cwd,
2286
+ maxParallelPhases: args.max_parallel_phases,
2287
+ maxAttemptsPerPhase: args.max_attempts_per_phase,
2288
+ maxRoundsPerPhase: args.max_rounds_per_phase,
2289
+ noProgressRounds: args.no_progress_rounds,
2290
+ phaseBudget: args.phase_budget
2291
+ ? {
2292
+ maxModelCalls: args.phase_budget.max_model_calls,
2293
+ maxTokens: args.phase_budget.max_tokens,
2294
+ }
2295
+ : undefined,
2296
+ budget: args.budget
2297
+ ? { maxModelCalls: args.budget.max_model_calls, maxTokens: args.budget.max_tokens }
2298
+ : undefined,
2299
+ maxWallClockMinutes: args.max_wall_clock_minutes,
2300
+ stallAfterMinutes: args.stall_after_minutes,
2301
+ autoResume: args.auto_resume,
2302
+ parentSessionId: check.agent.id,
2303
+ })
2304
+ const { goal, runs } = await longGoal.status(created.id)
2305
+ return `${formatLongGoal(goal, runs)}\n\nCreated in the background. Poll with `
2306
+ + `superagent_goal action=status goal_id=${goal.id}; phase runs continue after this call.`
2307
+ }
2308
+ if (action === 'list') {
2309
+ const limit = Math.max(1, Math.min(100, Number(args.limit) || 20))
2310
+ const goals = (await longGoal.list()).slice(0, limit)
2311
+ if (goals.length === 0) return 'No long-term goals recorded.'
2312
+ return goals.map(goal => {
2313
+ const phases = goal.phases ?? []
2314
+ const done = phases.filter(phase => phase.status === 'completed').length
2315
+ return `- ${goal.id} [${goal.status}] ${done}/${phases.length} phases — ${String(goal.goal).slice(0, 120)}`
2316
+ }).join('\n')
2317
+ }
2318
+ const goalId = String(args.goal_id ?? '').trim()
2319
+ if (!goalId) return describeError(`action=${action} requires goal_id`)
2320
+ if (action === 'status') {
2321
+ const { goal, runs } = await longGoal.status(goalId)
2322
+ return formatLongGoal(goal, runs)
2323
+ }
2324
+ if (action === 'answer') {
2325
+ const goal = await longGoal.answer(
2326
+ goalId,
2327
+ String(args.decision_id ?? '').trim(),
2328
+ args.answer,
2329
+ { note: args.note, parent: check.agent, clientTimeZone: exec.clientTimeZone },
2330
+ )
2331
+ const { goal: fresh, runs } = await longGoal.status(goal.id)
2332
+ return formatLongGoal(fresh, runs)
2333
+ }
2334
+ if (action === 'resume') {
2335
+ await longGoal.resume(goalId)
2336
+ } else if (action === 'pause') {
2337
+ await longGoal.pause(goalId)
2338
+ } else if (action === 'cancel') {
2339
+ await longGoal.cancel(goalId)
2340
+ } else {
2341
+ return describeError(`unknown action ${JSON.stringify(action)}`)
2342
+ }
2343
+ const { goal, runs } = await longGoal.status(goalId)
2344
+ return formatLongGoal(goal, runs)
2345
+ } catch (error) {
2346
+ return describeError(error)
2347
+ }
2348
+ },
2349
+ }), EXTRA_TOOLS)
2350
+
2079
2351
  // Files on disk can be newer than the code this host loaded: a package update
2080
2352
  // only takes effect after DSH restarts. Surface the mismatch instead of
2081
2353
  // letting the user wonder why the new version behaves like the old one.
@@ -2095,11 +2367,11 @@ export function apply(ctx, config) {
2095
2367
  ctx.tools.register(defineTool({
2096
2368
  name: 'superagent_status',
2097
2369
  description:
2098
- 'Read one superagent run: status, subtask outcomes, measured token usage, and the final report. '
2099
- + 'With wait_seconds it blocks until the run reaches a terminal state or the wait expires.',
2370
+ 'Read one run: status, subtask outcomes, measured token usage, and the final report. wait_seconds blocks for a '
2371
+ + 'terminal state.',
2100
2372
  properties: {
2101
2373
  run_id: { type: 'string', description: 'Run id returned by superagent_start.' },
2102
- wait_seconds: { type: 'number', description: 'Block up to this many seconds for a terminal state (default 0).' },
2374
+ wait_seconds: { type: 'number', description: 'Block up to this long for a terminal state (default 0).' },
2103
2375
  },
2104
2376
  required: ['run_id'],
2105
2377
  async execute(args = {}) {
@@ -2117,9 +2389,9 @@ export function apply(ctx, config) {
2117
2389
 
2118
2390
  ctx.tools.register(defineTool({
2119
2391
  name: 'superagent_list',
2120
- description: 'List recorded superagent runs, newest first, with status and progress.',
2392
+ description: 'List recorded runs, newest first, with status and progress.',
2121
2393
  properties: {
2122
- limit: { type: 'number', description: 'Maximum rows to print (default 20).' },
2394
+ limit: { type: 'number', description: 'Maximum rows (default 20).' },
2123
2395
  },
2124
2396
  async execute(args = {}) {
2125
2397
  try {
@@ -2152,11 +2424,40 @@ export function apply(ctx, config) {
2152
2424
  },
2153
2425
  }))
2154
2426
 
2427
+ // Every declaration is paid for on every request, so the capabilities most
2428
+ // sessions never touch are registered behind a per-session activation
2429
+ // condition: `superagent_help` names them and turns them on for that session.
2430
+ ctx.tools.register(defineTool({
2431
+ name: 'superagent_help',
2432
+ description:
2433
+ 'Show the extra superagent tools and when each applies: long-term goals, cron schedules, live steering, '
2434
+ + 'cross-run memory, workflow templates, audit export. Call this before using any of them.',
2435
+ properties: {},
2436
+ async execute(_args, exec) {
2437
+ const check = requireAgent(exec)
2438
+ if (check.error) return check.error
2439
+ const id = sessionKey(check.agent)
2440
+ if (id) {
2441
+ if (expandedSessions.size >= 2000) expandedSessions.clear()
2442
+ expandedSessions.add(id)
2443
+ }
2444
+ return [
2445
+ '已展开,下一步起可用(参数见各自 schema):',
2446
+ '- superagent_goal: 长期目标按阶段推进,多里程碑或必须按序时用;action=create/status/list/answer/resume/pause/cancel',
2447
+ '- superagent_schedule: 定时或按间隔自动起 run;action=create/list/pause/resume/delete/run-now',
2448
+ '- superagent_inject: 给正在跑的 worker 立刻发指令;不着急就用 superagent_followup',
2449
+ '- superagent_memory: 跨 run 笔记;action=list/search/set/forget,layer="user" 读写用户级事实',
2450
+ '- superagent_template: 工作流模板;action=list/show/expand/save/delete,expand 出 goal 再 start',
2451
+ '- superagent_audit: 查询或导出审计流水(tool.call、path.write、blocked、审批等)',
2452
+ '不确定就先 action=list 或 superagent_status 看现状。',
2453
+ ].join('\n')
2454
+ },
2455
+ }))
2456
+
2155
2457
  ctx.tools.register(defineTool({
2156
2458
  name: 'superagent_cancel',
2157
2459
  description:
2158
- 'Cancel a superagent run: stops running subtasks, marks the run cancelled, and keeps the state file '
2159
- + 'so the partial work stays inspectable.',
2460
+ 'Cancel a run: stops its subtasks and marks it cancelled; the state file stays inspectable.',
2160
2461
  properties: {
2161
2462
  run_id: { type: 'string', description: 'Run id to cancel.' },
2162
2463
  },
@@ -2184,20 +2485,18 @@ export function apply(ctx, config) {
2184
2485
  ctx.tools.register(defineTool({
2185
2486
  name: 'superagent_resume',
2186
2487
  description:
2187
- 'Resume a run that was interrupted by a host restart, ran out of time, or failed part way. '
2188
- + 'Completed subtasks are kept; pending and failed ones run again. A completed run is reopened only when it '
2189
- + 'holds an answer that never reached a prompt, so its aggregation can apply the decision.',
2488
+ 'Resume an interrupted, timed-out, or failed run: completed subtasks are kept, pending and failed ones run '
2489
+ + 'again.',
2190
2490
  properties: {
2191
2491
  run_id: { type: 'string', description: 'Run id to resume.' },
2192
- wait_seconds: { type: 'number', description: 'Block up to this many seconds for a terminal state (default 0).' },
2492
+ wait_seconds: { type: 'number', description: 'Block up to this long for a terminal state (default 0).' },
2193
2493
  force: {
2194
2494
  type: 'boolean',
2195
- description: 'Accepted for backward compatibility and ignored: a resume is never refused by maxActiveRuns.',
2495
+ description: 'Ignored; kept so older callers still validate.',
2196
2496
  },
2197
2497
  approve_policy: {
2198
2498
  type: 'boolean',
2199
- description: 'Release a resume that the permission policy holds for confirmation. The approval is '
2200
- + 'recorded in the audit trail. It cannot override a policy that denies the resume.',
2499
+ description: 'Release a resume the permission policy holds for confirmation.',
2201
2500
  },
2202
2501
  },
2203
2502
  required: ['run_id'],
@@ -2231,11 +2530,8 @@ export function apply(ctx, config) {
2231
2530
  ctx.tools.register(defineTool({
2232
2531
  name: 'superagent_followup',
2233
2532
  description:
2234
- 'Add an instruction to a run that is already executing, instead of starting a second run. This is not a live '
2235
- + 'channel to the running children: the host has no way to append a message to a child activation, so the '
2236
- + 'instruction is queued on the run and carried by the next prompt built for it — the next worker spawn or the '
2237
- + 'aggregation, whichever comes first. Subtasks that are already running or finished keep their results. The '
2238
- + 'reply states exactly which boundary it will reach.',
2533
+ 'Add an instruction to a run that is already executing instead of starting a second one. It is queued and '
2534
+ + 'carried by the next prompt built for the run; children already running are not interrupted.',
2239
2535
  properties: {
2240
2536
  run_id: { type: 'string', description: 'Run id returned by superagent_start.' },
2241
2537
  message: { type: 'string', description: 'The instruction or constraint to add.' },
@@ -2268,23 +2564,18 @@ export function apply(ctx, config) {
2268
2564
  ctx.tools.register(defineTool({
2269
2565
  name: 'superagent_inject',
2270
2566
  description:
2271
- 'Deliver an instruction into the workers that are running right now, instead of waiting for the next prompt. '
2272
- + 'The host reads steering at a child\'s next step boundary, so the message becomes part of that child\'s next '
2273
- + 'model request: it never interrupts a model call already in flight, and it arrives only after the current step '
2274
- + '(the model response plus its tool batch) finishes. A live child that had already decided to stop runs one more '
2275
- + 'turn to read it. The reply reports the measured delay from acceptance to the child\'s next request; a message '
2276
- + 'the child never claimed is reported as missed, never as delivered. Use superagent_followup when no worker is '
2277
- + 'running or the instruction can wait for the next prompt.',
2567
+ 'Deliver an instruction into the workers running right now: it becomes part of each child\'s next model request, '
2568
+ + 'at its next step boundary. Use superagent_followup when no worker is running.',
2278
2569
  properties: {
2279
2570
  run_id: { type: 'string', description: 'Run id returned by superagent_start.' },
2280
- message: { type: 'string', description: 'The instruction or constraint the running workers should read next.' },
2571
+ message: { type: 'string', description: 'The instruction the running workers should read next.' },
2281
2572
  subtask_index: {
2282
2573
  type: 'number',
2283
- description: 'Narrow delivery to one running worker, using its index from superagent_status. Omit to reach every running worker.',
2574
+ description: 'One worker, by its index from superagent_status; omit to reach every running worker.',
2284
2575
  },
2285
2576
  wait_seconds: {
2286
2577
  type: 'number',
2287
- description: 'Block up to this many seconds for the children to claim the message, so the reply can report the measured delay (default 0).',
2578
+ description: 'Block up to this long for the children to claim it, so the delay can be measured (default 0).',
2288
2579
  },
2289
2580
  },
2290
2581
  required: ['run_id', 'message'],
@@ -2306,24 +2597,21 @@ export function apply(ctx, config) {
2306
2597
  return describeError(error)
2307
2598
  }
2308
2599
  },
2309
- }))
2600
+ }), EXTRA_TOOLS)
2310
2601
 
2311
2602
  ctx.tools.register(defineTool({
2312
2603
  name: 'superagent_answer',
2313
2604
  description:
2314
- 'Answer a question a run asked — the "needs your decision" item with a qN id — so that run continues with the '
2315
- + 'decision instead of a new run being started. An active run applies it at its next boundary; a finished run '
2316
- + 'is reopened and only its aggregation runs again, now with the answer. The answer is matched to one specific '
2317
- + 'question: an unknown, already answered, or expired question is refused instead of being attached to whatever '
2318
- + 'is open.',
2605
+ 'Answer the question a run asked (the qN item in superagent_status), so that run continues instead of a new one '
2606
+ + 'starting. An active run applies it at its next boundary; a finished run is reopened for aggregation.',
2319
2607
  properties: {
2320
2608
  run_id: { type: 'string', description: 'Run id returned by superagent_start.' },
2321
2609
  attention_id: {
2322
2610
  type: 'string',
2323
- description: 'Question id from superagent_status, e.g. q1. Required when the run has more than one open question.',
2611
+ description: 'Question id from superagent_status, e.g. q1; required when several are open.',
2324
2612
  },
2325
- answer: { type: 'string', description: 'The decision itself; one of the listed options is enough, free text is allowed.' },
2326
- wait_seconds: { type: 'number', description: 'Block up to this many seconds for the run to settle again (default 0).' },
2613
+ answer: { type: 'string', description: 'The decision; a listed option or free text.' },
2614
+ wait_seconds: { type: 'number', description: 'Block up to this long for the run to settle (default 0).' },
2327
2615
  },
2328
2616
  required: ['run_id', 'answer'],
2329
2617
  async execute(args = {}, exec) {
@@ -2359,60 +2647,57 @@ export function apply(ctx, config) {
2359
2647
  ctx.tools.register(defineTool({
2360
2648
  name: 'superagent_memory',
2361
2649
  description:
2362
- 'Read or correct the cross-run notebook: short notes that earlier runs left for the next one. '
2363
- + 'A note is advisory and can be stale; a new note with the same key supersedes it, and forget retracts it. '
2364
- + 'With layer="user" (when the user-level profile is enabled) the same actions address durable facts, '
2365
- + 'preferences, and decisions with their rationale; forgetting there deletes instead of retracting.',
2650
+ 'Read or correct the cross-run notebook: short notes earlier runs left for the next one, or (layer="user") '
2651
+ + 'durable facts, preferences, and decisions.',
2366
2652
  properties: {
2367
2653
  action: {
2368
2654
  type: 'string',
2369
2655
  enum: ['list', 'search', 'set', 'forget'],
2370
- description: 'List notes, search them by keyword or tag, set (add or correct) one, or forget one.',
2656
+ description: 'List notes, search by keyword or tag, set one, or forget one.',
2371
2657
  },
2372
2658
  layer: {
2373
2659
  type: 'string',
2374
2660
  enum: ['run', 'user'],
2375
- description: 'run (default) reads the task notebook; user reads the cross-task profile.',
2661
+ description: 'run (default): task notebook. user: cross-task profile.',
2376
2662
  },
2377
2663
  category: {
2378
2664
  type: 'string',
2379
2665
  enum: [...USER_MEMORY_CATEGORIES],
2380
2666
  description: 'User layer only: fact, preference, or decision.',
2381
2667
  },
2382
- key: { type: 'string', description: 'Short topic key. A new note with the same key replaces the older one.' },
2668
+ key: { type: 'string', description: 'Short topic key; a new note with the same key replaces it.' },
2383
2669
  kind: { type: 'string', enum: [...MEMORY_KINDS], description: 'decision, pitfall, next, dispatch, or note.' },
2384
- text: { type: 'string', description: 'The durable fact to record (run, or user fact/preference).' },
2385
- choice: { type: 'string', description: 'User decision only: what was chosen.' },
2386
- rejected: { type: 'string', description: 'User decision only: the alternative that was given up.' },
2387
- reason: { type: 'string', description: 'User decision only: why the choice was made.' },
2388
- rollback: { type: 'string', description: 'User decision only: how to undo the choice later.' },
2670
+ text: { type: 'string', description: 'The durable fact to record.' },
2671
+ choice: { type: 'string', description: 'User decision: what was chosen.' },
2672
+ rejected: { type: 'string', description: 'User decision: the alternative given up.' },
2673
+ reason: { type: 'string', description: 'User decision: why.' },
2674
+ rollback: { type: 'string', description: 'User decision: how to undo it.' },
2389
2675
  query: {
2390
2676
  type: 'string',
2391
- description: 'Keywords to rank notes by (search only). The goal of the current task works well.',
2677
+ description: 'Search: keywords to rank notes by.',
2392
2678
  },
2393
2679
  tags: {
2394
2680
  type: 'array',
2395
2681
  items: { type: 'string' },
2396
- description: 'Topic labels to match exactly (search) or to attach to a note (set).',
2682
+ description: 'Match exactly (search) or attach (set).',
2397
2683
  },
2398
2684
  scope: {
2399
2685
  type: 'string',
2400
- description: 'Notebook scope: "rules" for project rules, "profile" for user preferences, '
2401
- + 'or the run scope (default) that earlier runs write to.',
2686
+ description: 'Notebook scope: "rules", "profile", or the run scope (default).',
2402
2687
  },
2403
2688
  run_id: {
2404
2689
  type: 'string',
2405
- description: 'User layer forget only: delete every record written by this run.',
2690
+ description: 'User layer forget: delete every record from this run.',
2406
2691
  },
2407
2692
  before: {
2408
2693
  type: 'string',
2409
- description: 'User layer forget only: delete records at or before this date.',
2694
+ description: 'User layer forget: delete records at or before this date.',
2410
2695
  },
2411
2696
  after: {
2412
2697
  type: 'string',
2413
- description: 'User layer forget only: delete records at or after this date.',
2698
+ description: 'User layer forget: delete records at or after this date.',
2414
2699
  },
2415
- limit: { type: 'number', description: 'Maximum notes to print (default 20).' },
2700
+ limit: { type: 'number', description: 'Maximum notes (default 20).' },
2416
2701
  },
2417
2702
  required: ['action'],
2418
2703
  async execute(args = {}, exec) {
@@ -2570,7 +2855,7 @@ export function apply(ctx, config) {
2570
2855
  return describeError(error)
2571
2856
  }
2572
2857
  },
2573
- }))
2858
+ }), EXTRA_TOOLS)
2574
2859
 
2575
2860
  /**
2576
2861
  * A template failure already names the concrete problem (which parameters
@@ -2594,28 +2879,24 @@ export function apply(ctx, config) {
2594
2879
  ctx.tools.register(defineTool({
2595
2880
  name: 'superagent_template',
2596
2881
  description:
2597
- 'List, show, expand, save, or delete a workflow template: a fixed goal skeleton with required parameters, '
2598
- + 'the situations it fits, and when it is the wrong tool. Expanding returns one normal goal string, which '
2599
- + 'superagent_start plans exactly like a goal typed by the user. A template cannot set limits, budgets, a '
2600
- + 'mode, or an override, so using one never widens what a run may do.',
2882
+ 'List, show, expand, save, or delete a workflow template: a fixed goal skeleton with required parameters. '
2883
+ + 'expand returns one goal string for superagent_start; a template never sets limits, budgets, or overrides.',
2601
2884
  properties: {
2602
2885
  action: {
2603
2886
  type: 'string',
2604
2887
  enum: ['list', 'show', 'expand', 'save', 'delete'],
2605
- description: 'List templates, show one in full, expand one into a goal, save a custom one, or delete a custom one.',
2888
+ description: 'List, show one, expand into a goal, save a custom one, or delete a custom one.',
2606
2889
  },
2607
- id: { type: 'string', description: 'Template id from action="list". Built-in ids are read-only.' },
2890
+ id: { type: 'string', description: 'Template id from action="list"; built-in ids are read-only.' },
2608
2891
  params: {
2609
2892
  type: 'object',
2610
- description: 'Values for the placeholders (expand only). Every declared parameter is required; a missing or '
2611
- + 'empty value is refused with its name instead of being given a default.',
2893
+ description: 'expand: a value for every declared parameter; missing ones are refused, not defaulted.',
2612
2894
  additionalProperties: { type: 'string' },
2613
2895
  },
2614
2896
  template: {
2615
2897
  type: 'object',
2616
- description: 'Complete definition (save only): id, title, whenToUse, whenNotToUse (list of strings), '
2617
- + 'variables (list of {name, description}), and skeleton with {{name}} placeholders. Unknown fields are '
2618
- + 'refused so a template cannot carry limits or overrides.',
2898
+ description: 'save: id, title, whenToUse, whenNotToUse, variables [{name, description}], '
2899
+ + 'skeleton with {{name}} placeholders.',
2619
2900
  },
2620
2901
  limit: { type: 'number', description: 'Maximum templates to list (default 50).' },
2621
2902
  },
@@ -2677,80 +2958,66 @@ export function apply(ctx, config) {
2677
2958
  return describeError(error)
2678
2959
  }
2679
2960
  },
2680
- }))
2961
+ }), EXTRA_TOOLS)
2681
2962
 
2682
2963
  ctx.tools.register(defineTool({
2683
2964
  name: 'superagent_schedule',
2684
2965
  description:
2685
- 'Create and manage scheduled runs: a plan that starts a run on a cron expression or a fixed interval, without '
2686
- + 'anyone calling superagent_start. Actions: create, list, pause, resume, delete, run-now. A plan stores its '
2687
- + 'cron or interval, time zone, goal (or template), optional goal mode and acceptance, its own budget, and its '
2688
- + 'concurrency policy. Plans survive a host restart under the state directory. '
2689
- + 'Missed windows are not replayed: the default miss policy "latest" runs only the newest due window and marks '
2690
- + 'the rest missed with a reason; "none" skips due windows while the host is down. '
2691
- + 'A plan never overlaps itself: if its previous run is still active, that window is recorded as '
2692
- + '"skipped: previous run still active". Scheduled runs share the concurrency quota with manual runs, and by '
2693
- + 'default one slot stays reserved for manual starts. Notifications are limited to achieved, first failure, '
2694
- + 'budget stop, and a needed decision; a plan that fails 3 times in a row pauses and says so once. '
2695
- + 'Cron support is zero-dependency: 5 fields, *, */n, ranges, lists, month/weekday names, 0 or 7 for Sunday. '
2696
- + 'Seconds, @macros, L, W, # and ? are refused when the plan is created, with the field number. '
2697
- + 'Nothing runs until a plan is created; an install with no plans behaves exactly as before.',
2966
+ 'Create and manage scheduled runs that start on a cron expression or fixed interval without anyone calling '
2967
+ + 'superagent_start. Actions: create, list, pause, resume, delete, run-now. Plans survive restarts, never overlap '
2968
+ + 'themselves, and pause after 3 consecutive failures. Cron is 5 fields (*, */n, ranges, lists, names, 0/7 '
2969
+ + 'Sunday); seconds and macros are refused.',
2698
2970
  properties: {
2699
2971
  action: {
2700
2972
  type: 'string',
2701
2973
  enum: ['create', 'list', 'pause', 'resume', 'delete', 'run-now'],
2702
- description: 'create a plan, list plans, pause/resume one, delete one, or start one run now without moving its '
2703
- + 'next planned window.',
2974
+ description: 'create, list, pause/resume, delete, or start one run now without moving the next window.',
2704
2975
  },
2705
- id: { type: 'string', description: 'Schedule id (sch-...), required for pause, resume, delete, and run-now.' },
2706
- name: { type: 'string', description: 'Create: a short name used in list and in notifications.' },
2976
+ id: { type: 'string', description: 'Schedule id (sch-...); required for pause, resume, delete, run-now.' },
2977
+ name: { type: 'string', description: 'create: short name used in list and notifications.' },
2707
2978
  goal: {
2708
2979
  type: 'string',
2709
- description: 'Create: the complete goal the scheduled run starts. Give goal or template_id, not both.',
2980
+ description: 'create: the complete goal the scheduled run starts. Give goal or template_id, not both.',
2710
2981
  },
2711
2982
  template_id: {
2712
2983
  type: 'string',
2713
- description: 'Create: expand this workflow template into the goal at create time, using params. The stored '
2714
- + 'goal is the expanded text, so a later template edit does not change the plan.',
2984
+ description: 'create: expand this template into the goal at create time.',
2715
2985
  },
2716
2986
  params: {
2717
2987
  type: 'object',
2718
- description: 'Create with template_id: values for the template placeholders.',
2988
+ description: 'create with template_id: values for the placeholders.',
2719
2989
  additionalProperties: { type: 'string' },
2720
2990
  },
2721
2991
  cron: {
2722
2992
  type: 'string',
2723
- description: 'Create: a 5-field cron expression (minute hour day-of-month month day-of-week) evaluated in '
2724
- + 'timezone, e.g. "0 9 * * MON-FRI". Give cron or every_minutes, not both.',
2993
+ description: 'create: 5-field cron (minute hour day month weekday) in timezone, e.g. "0 9 * * MON-FRI". '
2994
+ + 'Give cron or every_minutes, not both.',
2725
2995
  },
2726
2996
  every_minutes: {
2727
2997
  type: 'number',
2728
- description: 'Create: a fixed interval in minutes instead of cron. The first run is one interval from now; '
2729
- + 'later runs are one interval after the previous planned window.',
2998
+ description: 'create: fixed interval instead of cron; first run one interval from now.',
2730
2999
  },
2731
3000
  timezone: {
2732
3001
  type: 'string',
2733
- description: 'Create: IANA time zone the cron is written in (default UTC), e.g. "Asia/Shanghai". The host '
2734
- + 'clock is not used as an implicit zone.',
3002
+ description: 'create: IANA zone the cron is written in (default UTC), e.g. "Asia/Shanghai".',
2735
3003
  },
2736
3004
  miss_policy: {
2737
3005
  type: 'string',
2738
3006
  enum: ['latest', 'none'],
2739
- description: 'Create: what to do after downtime. latest (default) runs only the newest missed window and marks '
2740
- + 'the others missed; none skips all due windows and advances to the next one.',
3007
+ description: 'create: after downtime, latest (default) runs the newest missed window; none skips them.',
2741
3008
  },
2742
3009
  mode: {
2743
3010
  type: 'string',
2744
3011
  enum: ['planned', 'direct'],
2745
- description: 'Create: run mode for each execution, same meaning as superagent_start.',
3012
+ description: 'create: run mode per execution, as in superagent_start.',
2746
3013
  },
2747
3014
  goal_mode: {
2748
3015
  type: 'boolean',
2749
- description: 'Create: run each execution in goal mode with acceptance checking and self-continuation.',
3016
+ description: 'create: run each execution in goal mode with acceptance checking.',
2750
3017
  },
2751
3018
  acceptance: {
2752
3019
  type: 'array',
2753
- description: 'Create with goal_mode: acceptance conditions, same shape as superagent_start.',
3020
+ description: 'create with goal_mode: conditions, same shape as superagent_start.',
2754
3021
  items: {
2755
3022
  type: 'object',
2756
3023
  properties: {
@@ -2772,14 +3039,13 @@ export function apply(ctx, config) {
2772
3039
  required: ['text'],
2773
3040
  },
2774
3041
  },
2775
- max_rounds: { type: 'number', description: 'Create with goal_mode: rounds per execution (default 5, max 20).' },
2776
- max_wall_clock_minutes: { type: 'number', description: 'Create with goal_mode: wall-clock budget per execution.' },
2777
- no_progress_rounds: { type: 'number', description: 'Create with goal_mode: no-progress rounds before stopping.' },
3042
+ max_rounds: { type: 'number', description: 'create with goal_mode: rounds per execution (default 5, max 20).' },
3043
+ max_wall_clock_minutes: { type: 'number', description: 'create with goal_mode: wall-clock budget per execution.' },
3044
+ no_progress_rounds: { type: 'number', description: 'create with goal_mode: no-progress rounds before stopping.' },
2778
3045
  budget: {
2779
3046
  type: 'object',
2780
- description: 'Create: spending ceiling. max_model_calls and max_tokens cap one execution; '
2781
- + 'max_total_model_calls, max_total_tokens and max_total_runs cap the plan across executions. A reached '
2782
- + 'total pauses the plan and records the reason.',
3047
+ description: 'create: per-execution caps (max_model_calls, max_tokens) and whole-plan caps '
3048
+ + '(max_total_model_calls, max_total_tokens, max_total_runs).',
2783
3049
  properties: {
2784
3050
  max_model_calls: { type: 'number' },
2785
3051
  max_tokens: { type: 'number' },
@@ -2790,15 +3056,11 @@ export function apply(ctx, config) {
2790
3056
  },
2791
3057
  human_priority: {
2792
3058
  type: 'boolean',
2793
- description: 'Create: when true (default), a scheduled run may not take the last concurrency slot, so a '
2794
- + 'manual superagent_start at the same moment still finds room.',
3059
+ description: 'create: when true (default), a scheduled run cannot take the last slot a manual start needs.',
2795
3060
  },
2796
3061
  session_id: {
2797
3062
  type: 'string',
2798
- description: 'Create: the session that owns the scheduled runs and receives their notifications. Defaults to '
2799
- + 'the calling session. After a host restart the plugin asks the Host Session API to reopen that session, '
2800
- + 'and creates a replacement if it was deleted, so a plan does not depend on the original process staying '
2801
- + 'alive. On a host without that API the plan is marked at create time as requiring a resident session.',
3063
+ description: 'create: session that owns the runs and receives notifications (default: this session).',
2802
3064
  },
2803
3065
  },
2804
3066
  required: ['action'],
@@ -2884,7 +3146,7 @@ export function apply(ctx, config) {
2884
3146
  return describeError(error)
2885
3147
  }
2886
3148
  },
2887
- }))
3149
+ }), EXTRA_TOOLS)
2888
3150
 
2889
3151
  // The embedding surface is opt-in: mounting the plugin must not open a port
2890
3152
  // unasked. When it is on, every request goes through the same orchestrator as
@@ -2893,22 +3155,21 @@ export function apply(ctx, config) {
2893
3155
  ctx.tools.register(defineTool({
2894
3156
  name: 'superagent_audit',
2895
3157
  description:
2896
- 'Query the append-only audit trail (tool calls, path writes, commands, blocks, approvals, attention '
2897
- + 'decisions, run lifecycle) for one run or a time window, or export the matching events as a single '
2898
- + 'JSONL or CSV file.',
3158
+ 'Query the append-only audit trail (tool calls, path writes, commands, blocks, approvals, decisions, run '
3159
+ + 'lifecycle) for one run or a time window, or export the matching events as JSONL or CSV.',
2899
3160
  properties: {
2900
3161
  run_id: { type: 'string', description: 'Only events for this run id.' },
2901
3162
  subtask_id: { type: 'string', description: 'Only events for one subtask, e.g. "subtask-2" or "aggregator".' },
2902
3163
  kind: { type: 'string', description: 'Event kind, e.g. tool.call, path.write, command.exec, blocked, approved, attention.' },
2903
- decision: { type: 'string', description: 'Only events with this decision: allow, confirm, or deny.' },
2904
- result: { type: 'string', description: 'Only events with this result, e.g. ok, blocked, pending, approved, failed.' },
2905
- target: { type: 'string', description: 'Substring of the path, command, or question the event is about.' },
2906
- since: { type: 'string', description: 'ISO timestamp; events before it are skipped.' },
2907
- until: { type: 'string', description: 'ISO timestamp; events after it are skipped.' },
2908
- limit: { type: 'number', description: 'Maximum events to read or rows to print (default 8 for the summary, all for an export).' },
3164
+ decision: { type: 'string', description: 'allow, confirm, or deny.' },
3165
+ result: { type: 'string', description: 'e.g. ok, blocked, pending, approved, failed.' },
3166
+ target: { type: 'string', description: 'Substring of the path, command, or question.' },
3167
+ since: { type: 'string', description: 'ISO timestamp; earlier events are skipped.' },
3168
+ until: { type: 'string', description: 'ISO timestamp; later events are skipped.' },
3169
+ limit: { type: 'number', description: 'Maximum events read or rows printed (default 8 for summary, all for export).' },
2909
3170
  order: { type: 'string', description: 'asc (oldest first, default) or desc.' },
2910
- format: { type: 'string', description: 'summary (default), jsonl, or csv. jsonl and csv write a file and return its path.' },
2911
- out_path: { type: 'string', description: 'File to write for jsonl/csv. Defaults to <stateDir>/audit/audit-export-<time>.<ext>.' },
3171
+ format: { type: 'string', description: 'summary (default), jsonl, or csv; the last two write a file and return its path.' },
3172
+ out_path: { type: 'string', description: 'File for jsonl/csv; defaults to <stateDir>/audit/audit-export-<time>.<ext>.' },
2912
3173
  },
2913
3174
  async execute(args = {}) {
2914
3175
  try {
@@ -2944,7 +3205,7 @@ export function apply(ctx, config) {
2944
3205
  return describeError(error)
2945
3206
  }
2946
3207
  },
2947
- }))
3208
+ }), EXTRA_TOOLS)
2948
3209
  }
2949
3210
 
2950
3211
  if (cfg.controlPort !== null) {
@@ -3965,9 +4226,10 @@ export function apply(ctx, config) {
3965
4226
  scheduleOwners.clear()
3966
4227
  }
3967
4228
  if (typeof ctx.on === 'function') ctx.on('dispose', stopScheduler)
4229
+ if (typeof ctx.on === 'function') ctx.on('dispose', () => longGoal.close())
3968
4230
 
3969
4231
  log(
3970
- `registered ${auditor ? 12 : 11} tools; state ${store.root}`
4232
+ `registered ${auditor ? 13 : 12} tools; state ${store.root}`
3971
4233
  + `${cfg.controlPort === null ? '' : `; control port ${cfg.controlPort}`}`
3972
4234
  + `${cfg.workbenchPort === null ? '' : `; workbench ${workbenchRoot} on port ${cfg.workbenchPort}`}`
3973
4235
  + `${cfg.consolePort === null ? '' : `; console on port ${cfg.consolePort}`}`