@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/CHANGELOG.md +59 -0
- package/README.en.md +22 -10
- package/README.md +21 -9
- package/README.zh.md +26 -14
- package/bin/doctor.js +1 -1
- package/docs/LONG-GOAL.md +223 -0
- package/lib/doctor.js +2 -0
- package/lib/index.js +456 -194
- package/lib/long-goal.js +1705 -0
- package/lib/orchestrator.js +79 -16
- package/package.json +5 -3
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
|
|
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
|
-
//
|
|
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
|
-
'
|
|
1262
|
-
'
|
|
1263
|
-
'
|
|
1264
|
-
'
|
|
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
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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
|
|
1933
|
-
+ '
|
|
1934
|
-
+ '
|
|
1935
|
-
+ '
|
|
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
|
|
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):
|
|
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: '
|
|
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: '
|
|
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: '
|
|
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
|
|
1976
|
-
text: { type: 'string', description: 'What must hold
|
|
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
|
|
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
|
|
1983
|
-
cwd: { type: 'string', description: '
|
|
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
|
|
1986
|
-
must_exist: { type: 'boolean', description: '
|
|
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
|
|
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:
|
|
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,
|
|
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: `
|
|
2013
|
-
max_parallel: { type: 'number', description: `Subtasks
|
|
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
|
|
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
|
|
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
|
|
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
|
|
2099
|
-
+ '
|
|
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
|
|
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
|
|
2392
|
+
description: 'List recorded runs, newest first, with status and progress.',
|
|
2121
2393
|
properties: {
|
|
2122
|
-
limit: { type: 'number', description: 'Maximum rows
|
|
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
|
|
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
|
|
2188
|
-
+ '
|
|
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
|
|
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: '
|
|
2495
|
+
description: 'Ignored; kept so older callers still validate.',
|
|
2196
2496
|
},
|
|
2197
2497
|
approve_policy: {
|
|
2198
2498
|
type: 'boolean',
|
|
2199
|
-
description: 'Release a resume
|
|
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
|
|
2235
|
-
+ '
|
|
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
|
|
2272
|
-
+ '
|
|
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
|
|
2571
|
+
message: { type: 'string', description: 'The instruction the running workers should read next.' },
|
|
2281
2572
|
subtask_index: {
|
|
2282
2573
|
type: 'number',
|
|
2283
|
-
description: '
|
|
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
|
|
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
|
|
2315
|
-
+ '
|
|
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
|
|
2611
|
+
description: 'Question id from superagent_status, e.g. q1; required when several are open.',
|
|
2324
2612
|
},
|
|
2325
|
-
answer: { type: 'string', description: 'The decision
|
|
2326
|
-
wait_seconds: { type: 'number', description: 'Block up to this
|
|
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
|
|
2363
|
-
+ '
|
|
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
|
|
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)
|
|
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
|
|
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
|
|
2385
|
-
choice: { type: 'string', description: 'User decision
|
|
2386
|
-
rejected: { type: 'string', description: 'User decision
|
|
2387
|
-
reason: { type: 'string', description: 'User decision
|
|
2388
|
-
rollback: { type: 'string', description: 'User decision
|
|
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: '
|
|
2677
|
+
description: 'Search: keywords to rank notes by.',
|
|
2392
2678
|
},
|
|
2393
2679
|
tags: {
|
|
2394
2680
|
type: 'array',
|
|
2395
2681
|
items: { type: 'string' },
|
|
2396
|
-
description: '
|
|
2682
|
+
description: 'Match exactly (search) or attach (set).',
|
|
2397
2683
|
},
|
|
2398
2684
|
scope: {
|
|
2399
2685
|
type: 'string',
|
|
2400
|
-
description: 'Notebook scope: "rules"
|
|
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
|
|
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
|
|
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
|
|
2698
|
+
description: 'User layer forget: delete records at or after this date.',
|
|
2414
2699
|
},
|
|
2415
|
-
limit: { type: 'number', description: 'Maximum notes
|
|
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
|
-
+ '
|
|
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
|
|
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"
|
|
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: '
|
|
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: '
|
|
2617
|
-
+ '
|
|
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
|
|
2686
|
-
+ '
|
|
2687
|
-
+ '
|
|
2688
|
-
+ '
|
|
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
|
|
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-...)
|
|
2706
|
-
name: { type: 'string', description: '
|
|
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: '
|
|
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: '
|
|
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: '
|
|
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: '
|
|
2724
|
-
+ '
|
|
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: '
|
|
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: '
|
|
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: '
|
|
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: '
|
|
3012
|
+
description: 'create: run mode per execution, as in superagent_start.',
|
|
2746
3013
|
},
|
|
2747
3014
|
goal_mode: {
|
|
2748
3015
|
type: 'boolean',
|
|
2749
|
-
description: '
|
|
3016
|
+
description: 'create: run each execution in goal mode with acceptance checking.',
|
|
2750
3017
|
},
|
|
2751
3018
|
acceptance: {
|
|
2752
3019
|
type: 'array',
|
|
2753
|
-
description: '
|
|
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: '
|
|
2776
|
-
max_wall_clock_minutes: { type: 'number', description: '
|
|
2777
|
-
no_progress_rounds: { type: 'number', description: '
|
|
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: '
|
|
2781
|
-
+ 'max_total_model_calls, max_total_tokens
|
|
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: '
|
|
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: '
|
|
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,
|
|
2897
|
-
+ '
|
|
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: '
|
|
2904
|
-
result: { type: 'string', description: '
|
|
2905
|
-
target: { type: 'string', description: 'Substring of the path, command, or question
|
|
2906
|
-
since: { type: 'string', description: 'ISO timestamp; events
|
|
2907
|
-
until: { type: 'string', description: 'ISO timestamp; events
|
|
2908
|
-
limit: { type: 'number', description: 'Maximum events
|
|
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
|
|
2911
|
-
out_path: { type: 'string', description: 'File
|
|
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 ?
|
|
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}`}`
|