🤖 Open-source, local-first alternative to Grok Bot, OpenAI dots and Claude Duet. Your own AI bots on any model: GPT, Claude, Gemini, Grok, DeepSeek, Kimi, GLM and 70+ more through one Modelflare key. Reach them in the app, WeChat or Feishu; they remember you, work in the background, run commands and use your computer. Pay per use.
Python ai-agentai-assistantchatbotclaudecomputer-usedeepseekdesktop-appdshelectronfeishugeminigptgrokllmlocal-firstmodelflaremulti-modelopenai-compatiblepersonal-ai-agentwechat
// anymodel bot background tasks (MIT, part of anymodel bot).
//
// The host creates one DSH session per background task over the SDK (`task-<id>`, its own folder as working
// directory) and owns tasks, runs and delivery. This plugin decorates those sessions on agent/created, which also
// fires for sessions resumed after a restart:
// - denies the chat-only tools (present, ask_user_question and the task tools; only registered names, since
// tools.restrict throws on unknown ones),
// - adds the task rules (AMB_TASK_RULES, written by the host) as the last system-prompt section,
// - registers task_report, which reports the task's state to the host (needs_you carries one question for the
// user, only when the task cannot decide itself; the host asks it right away and hands the answer back as an
// input: with a default the task keeps working and the answer reaches its next step, without one the task ends
// its turn and waits),
// - refuses every tool call once the host has stopped the task.
// Chat sessions get task_start / task_message / task_list, rule_create / rule_update and background_pause (pause or
// resume all of the bot's background work); subagents get none of them.
//
// Rule sessions (`rule-<rule>-<run>`, one fresh session per run of a standing rule, 3d) are decorated from the host's
// answer to /dsh/task-config (the host owns the mode): the denied tools (observe denies everything that acts), the rule
// section, a rule variant of task_report (done with or without a message, failed, progress; no needs_you) and the
// session's sandbox (observe: read-only; act: at most workspace-write), which amb-permission applies before every tool
// call through a shared per-session map. Subagents of a rule session inherit its config. If the host cannot be
// reached the session fails closed: read-only and every tool refused.
//
// Settling: when a task session goes idle the host asks `task-quiet` over the control channel (amb-control hands
// the ops it does not know to this plugin). A session that still owns running background jobs or subagents is not
// quiet; the plugin then watches it and posts /dsh/task-settled once it is idle with nothing running and nothing
// queued for it, or stops its jobs AMB_TASK_SETTLE_MS (30 minutes) after its last turn and says which. `task-stop`
// cancels the turn, its subagents and every job the session owns. `task-cancel` does the same but leaves the session
// usable (the host stopped it at its budget or time cap, and continues it later).
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'amb-tasks'
export const inject = ['tools']
/** Shared with amb-control: control-channel ops this plugin answers. */
export const HANDLERS = Symbol.for('amb.control.handlers')
export const CHAT_TOOLS = ['task_start', 'task_message', 'task_list', 'rule_create', 'rule_update', 'background_pause']
/** Tools a task session never gets (filtered to registered names before tools.restrict). */
export const TASK_DENY = ['present', 'ask_user_question', ...CHAT_TOOLS]
/** Shared with amb-permission: sessionId → DSH permission preset for rule sessions (and their subagents). */
export const PRESETS = Symbol.for('amb.session.presets')
export const SECTION = 'amb:task'
/** After the bot's section (amb:bot, 20000): the task rules win over the chat rules. */
export const ORDER = 20_100
const SETTLE_MAX_MS = Number(process.env.AMB_TASK_SETTLE_MS) > 0 ? Number(process.env.AMB_TASK_SETTLE_MS) : 30 * 60_000
const WATCH_MS = 1_000
const live = (status) => status === 'running' || status === 'stopping'
export const isTask = (id) => /^task-/.test(String(id ?? ''))
export const isRule = (id) => /^rule-/.test(String(id ?? ''))
/** Rule session when the host cannot be reached: read-only, every tool refused (fail closed). */
const RULE_FALLBACK = { mode: 'observe', deny: [], denyPrefix: [], section: '', permission: 'read-only', offline: true }
function bridge() {
const url = process.env.AMB_BRIDGE_URL
const token = process.env.AMB_BRIDGE_TOKEN
if (!url || !token) return undefined
return async (path, body, signal) => {
const res = await fetch(url + path, {
method: 'POST',
headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
body: JSON.stringify(body),
signal,
})
if (!res.ok) throw new Error(`bridge ${path} ${res.status}`)
return res.json()
}
}
const TEXT_OUT = {
schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
render: (_args, value) => [{ type: 'text', text: value.text }],
}
export function apply(ctx) {
const call = bridge()
const botId = process.env.AMB_BOT_ID ?? ''
const rules = process.env.AMB_TASK_RULES ?? ''
/** task sessions the host stopped: every tool call is refused */
const stopped = new Set()
/** task sessions being watched until they are quiet: id → { since, timer } */
const watching = new Map()
/** rule sessions and their subagents: id → the host's config for the run */
const ruleConfigs = new Map()
const presets = (globalThis[PRESETS] ??= new Map())
const agents = () => ctx.get('agents')
const jobs = () => ctx.get('jobs')
const sessionOf = (exec) => String(exec?.agent?.session?.id ?? exec?.agent?.id ?? '')
const host = async (path, body, signal) => {
if (!call) throw new Error('the app is not reachable')
const r = await call(path, { botId, ...body }, signal)
if (r?.error) throw new Error(String(r.error))
return { text: String(r?.text ?? '') }
}
// ---------- chat sessions: start, message and list background tasks ----------
if (call) {
const tool = (op) => (args, exec) => host('/dsh/task-tool', { sessionId: sessionOf(exec), op, args }, exec.signal)
ctx.tools.register(defineTool({
name: 'task_start',
description: 'Start a background task in its own session and folder; the user keeps chatting and the result is sent to this chat when done. Use it for work that clearly needs more than a few minutes or many steps (build, research, a report), or when the user asks for it in the background (后台做); not for what you can answer now, or when they want it done here (前台做). Then tell the user in one sentence what runs in the background; do not do the work yourself.',
parameters: {
title: { type: 'string', required: true, description: 'Short title in the user\'s language.' },
brief: { type: 'string', required: true, description: 'What to do and what result to give, at most 1,500 characters. The user\'s words and the recent chat are added automatically.' },
anytime: { type: 'boolean', description: 'true only when the user asked to be told the moment it is done, even at night. Otherwise a result that is ready during their quiet hours waits until morning.' },
budget_usd: { type: 'number', description: 'Only when the user names a spending limit, in US dollars. Default 1.' },
},
output: TEXT_OUT,
execute: tool('start'),
}))
ctx.tools.register(defineTool({
name: 'task_message',
description: 'Pass the user\'s message to one of their background tasks when they refer to it or answer its question: a working task sees it at its next step, a finished or waiting one resumes with it.',
parameters: {
task: { type: 'string', required: true, description: 'Task id or part of its title.' },
text: { type: 'string', required: true, description: 'The message, in the user\'s words.' },
},
output: TEXT_OUT,
execute: tool('message'),
}))
ctx.tools.register(defineTool({
name: 'task_list',
description: 'List this chat\'s background tasks and rules with their state and latest result.',
parameters: {},
output: TEXT_OUT,
execute: tool('list'),
}))
ctx.tools.register(defineTool({
name: 'rule_create',
description: 'Set up a standing rule the user asks for: a recurring check (kind check; it acts right away and tells the user only when it matters) or a fixed reminder (kind remind: sends message at the time). Confirm in one sentence.',
parameters: {
title: { type: 'string', required: true, description: 'Short, e.g. 看 X 价格.' },
instruction: { type: 'string', required: true, description: 'The user\'s words, verbatim.' },
schedule: { type: 'string', required: true, description: 'Local time: once YYYY-MM-DD HH:MM | daily HH:MM | weekdays HH:MM | weekly mon,thu HH:MM | every 30m | cron M H DOM MON DOW' },
kind: { type: 'string', enum: ['check', 'remind'] },
mode: { type: 'string', enum: ['act', 'observe'], description: 'observe only when the user wants to watch first (先观察): it only records what it would say.' },
message: { type: 'string', description: 'remind: the line to send.' },
},
output: TEXT_OUT,
execute: tool('rule_create'),
}))
ctx.tools.register(defineTool({
name: 'rule_update',
description: 'Change a rule of this chat when the user asks: mode act (results are sent), observe (only records) or off; new instruction or schedule; or delete.',
parameters: {
rule: { type: 'string', required: true, description: 'Rule id or part of its title.' },
mode: { type: 'string', enum: ['observe', 'act', 'off'] },
instruction: { type: 'string' },
schedule: { type: 'string' },
delete: { type: 'boolean' },
},
output: TEXT_OUT,
execute: tool('rule_update'),
}))
ctx.tools.register(defineTool({
name: 'background_pause',
description: 'Pause or resume all of this bot\'s background work when the user asks. Paused: no task or rule runs, pushed messages wait; chat still works.',
parameters: {
paused: { type: 'boolean', required: true },
},
output: TEXT_OUT,
execute: tool('pause'),
}))
}
const known = (names) => {
const tools = ctx.get('tools') ?? ctx.tools
return names.filter((n) => {
try {
return tools.get(n) !== undefined
} catch {
return false
}
})
}
const reportTool = () => defineTool({
name: 'task_report',
description: 'Report this background task\'s state to the app. done: finished. failed: you cannot finish it. For both, message is the one line the user receives (at most 300 characters, in their language): the result, where it is and what you chose; files are files to send them. needs_you only if a wrong guess could cause harm, cost money or waste most of the work, you need something only the user has, or the step cannot be undone; decide everything else yourself. The app asks the user question now. With default (rare), keep working on what does not depend on the answer; if you finish first, use default and say so in message. Without default, their answer is your next message. progress is recorded, never sent. After done, failed or needs_you without default, end your turn.',
parameters: {
state: { type: 'string', required: true, enum: ['progress', 'needs_you', 'done', 'failed'] },
summary: { type: 'string', required: true, description: 'What you did and found, for the record (not sent to the user).' },
message: { type: 'string', description: 'For done and failed: the one line for the user.' },
files: { type: 'array', items: { type: 'string' }, description: 'Paths of files to send to the user, relative to your folder.' },
question: { type: 'string', description: 'For needs_you: one short question.' },
options: { type: 'array', items: { type: 'string' }, description: 'For needs_you: choices, if any.' },
default: { type: 'string', description: 'For needs_you: the answer you go with if they do not reply (one of options). Omit it when only the user can decide.' },
},
output: TEXT_OUT,
execute: (args, exec) => host('/dsh/task-report', { sessionId: sessionOf(exec), ...args }, exec.signal),
})
const ruleReportTool = (mode) => defineTool({
name: 'task_report',
description: `Report this check to the app. done: finished; message is the one line for the user (at most 300 characters, in their language) only when they should hear about it${mode === 'observe' ? ' (observe mode: it is only recorded)' : ''}; leave it out to stay quiet. failed: you could not check, with the reason. progress is recorded, never sent. Then end your turn.`,
parameters: {
state: { type: 'string', required: true, enum: ['progress', 'done', 'failed'] },
summary: { type: 'string', required: true, description: 'What you checked and found, for the record.' },
message: { type: 'string', description: 'For done: the one line for the user, or nothing.' },
...(mode === 'observe' ? { would: { type: 'string', description: 'What you would have done if you could act.' } } : {}),
},
output: TEXT_OUT,
execute: (args, exec) => host('/dsh/task-report', { sessionId: sessionOf(exec), ...args }, exec.signal),
})
/** The host's config for a rule run (mode, denied tools, section, sandbox); fail closed when it cannot be reached. */
async function ruleConfig(id) {
if (!call) return RULE_FALLBACK
try {
const r = await call('/dsh/task-config', { botId, sessionId: id }, AbortSignal.timeout(10_000))
if (r?.error || r?.kind !== 'rule') throw new Error(String(r?.error ?? 'not a rule session'))
return { mode: r.mode === 'act' ? 'act' : 'observe', deny: r.deny ?? [], denyPrefix: r.denyPrefix ?? [], section: String(r.section ?? ''), permission: r.permission === 'workspace-write' ? 'workspace-write' : 'read-only' }
} catch (e) {
ctx.logger?.warn?.(`amb-tasks: no config for rule session ${id}: ${e?.message ?? e}`)
return RULE_FALLBACK
}
}
/** Deny the rule's tools (exact names; computer use by prefix) and pin its sandbox; the same for its subagents. */
function applyRule(agent, id, cfg, root) {
ruleConfigs.set(id, { ...cfg, root })
presets.set(id, cfg.permission)
// the guard first: if anything below fails, the session is still refused what it must not do
agent.ctx.tools.guard?.((exec) => {
if (cfg.offline) return 'The app cannot be reached, so this check cannot run. End your turn.'
if (stopped.has(root)) return 'This check was stopped. End your turn.'
const name = String(exec?.name ?? exec?.tool?.name ?? '')
if (cfg.denyPrefix.some((p) => name.startsWith(p)) || cfg.deny.includes(name)) return 'This tool is not available while running a rule.'
return undefined
})
const deny = known([...new Set([...TASK_DENY, ...cfg.deny])])
if (deny.length) agent.ctx.tools.restrict({ deny })
}
// ---------- decorate task sessions (created over the SDK, or resumed after a restart) ----------
const decorated = new WeakSet()
ctx.on('agent/created', async ({ agent }) => {
if (!agent || decorated.has(agent)) return
decorated.add(agent)
const id = String(agent.id ?? '')
const parent = agent.session?.header?.parentSession
try {
if (isRule(id)) {
const cfg = await ruleConfig(id)
applyRule(agent, id, cfg, id)
if (cfg.section) agent.ctx.systemPrompt?.section({ name: SECTION, order: ORDER, interpolate: false, text: () => cfg.section })
if (call && !cfg.offline) agent.ctx.tools.register(ruleReportTool(cfg.mode))
} else if (parent && ruleConfigs.has(String(parent))) {
// a subagent of a rule session (or of its subagent): same sandbox and denied tools
const cfg = ruleConfigs.get(String(parent))
applyRule(agent, id, cfg, cfg.root)
} else if (isTask(id)) {
const deny = known(TASK_DENY)
if (deny.length) agent.ctx.tools.restrict({ deny })
if (rules) agent.ctx.systemPrompt?.section({ name: SECTION, order: ORDER, interpolate: false, text: () => rules })
if (call) agent.ctx.tools.register(reportTool())
agent.ctx.tools.guard?.(() => (stopped.has(id) ? 'This background task was stopped by the user. Do not continue; end your turn.' : undefined))
} else if (agent.session?.header?.parentSession) {
// subagents (of chats and of tasks) do not start or manage tasks
const deny = known(CHAT_TOOLS)
if (deny.length) agent.ctx.tools.restrict({ deny })
}
} catch (e) {
ctx.logger?.warn?.(`amb-tasks: could not decorate ${id}: ${e?.message ?? e}`)
}
})
// ---------- settling and stop (control-channel ops) ----------
function descendants(agent) {
const registry = agents()
const out = []
const walk = (parent) => {
for (const a of registry?.list?.() ?? []) {
if (a !== parent && registry.isOwnedBy?.(a.id, parent)) {
out.push(a)
walk(a)
}
}
}
walk(agent)
return out
}
const runningJobs = (id) => (jobs()?.list(id) ?? []).filter((j) => j.owner === id && live(j.status))
const queued = (agent) => {
try {
return (agent.inbox?.nextTurn?.length ?? 0) + (agent.inbox?.nextStep?.length ?? 0)
} catch {
return 0
}
}
/** idle, no inbox, no running job or subagent */
const quiet = (agent) => agent.status === 'idle' && !queued(agent) && !runningJobs(String(agent.id)).length && !descendants(agent).some((a) => a.status === 'running')
async function killJobs(id, why) {
const registry = jobs()
const list = runningJobs(id)
const waits = list.map((j) => registry.wait(j.id, 5_000, id).catch(() => undefined))
for (const j of list) try { registry.kill(j.id, id, why) } catch {}
await Promise.all(waits)
return list.map((j) => String(j.description ?? j.command ?? j.id))
}
function unwatch(id) {
const w = watching.get(id)
if (w) clearTimeout(w.timer)
watching.delete(id)
}
/** Watch a task session until it is quiet twice in a row (a finished job wakes it a moment later), then report. */
function watch(id) {
if (watching.has(id)) return
const w = { since: Date.now(), calm: 0, timer: undefined }
watching.set(id, w)
const tick = async () => {
if (watching.get(id) !== w) return
const agent = agents()?.get(id)
let killedJobs = []
if (agent && agent.status !== 'idle') {
w.since = Date.now()
w.calm = 0
} else if (agent && !quiet(agent)) {
w.calm = 0
if (Date.now() - w.since < SETTLE_MAX_MS) return void (w.timer = setTimeout(tick, WATCH_MS))
killedJobs = await killJobs(id, 'the task stopped waiting for it')
for (const a of descendants(agent)) try { a.cancel({ kind: 'parent' }) } catch {}
} else if (agent && ++w.calm < 2) return void (w.timer = setTimeout(tick, WATCH_MS))
if (agent && agent.status !== 'idle') return void (w.timer = setTimeout(tick, WATCH_MS))
unwatch(id)
await call?.('/dsh/task-settled', { botId, sessionId: id, killedJobs }).catch(() => {})
}
w.timer = setTimeout(tick, WATCH_MS)
}
const handlers = (globalThis[HANDLERS] ??= {})
handlers['task-quiet'] = async ({ sessionId }) => {
const id = String(sessionId)
const agent = agents()?.get(id)
if (!agent || quiet(agent)) return { quiet: true }
watch(id)
return { quiet: false, jobs: runningJobs(id).map((j) => String(j.id)) }
}
/** Cancel the turn, its subagents and the session's jobs; `stop` also refuses every later tool call. */
async function halt(sessionId, stop, why) {
const id = String(sessionId)
if (stop) stopped.add(id)
unwatch(id)
const agent = agents()?.get(id)
if (!agent) return { running: false }
for (const child of descendants(agent)) try { child.cancel({ kind: 'parent' }) } catch {}
try { agent.cancel({ kind: 'user' }, { keepInbox: false }) } catch {}
const killed = await killJobs(id, why).catch(() => [])
return { running: true, killed }
}
handlers['task-stop'] = ({ sessionId }) => halt(sessionId, true, 'stopped by the user')
handlers['task-cancel'] = ({ sessionId }) => halt(sessionId, false, 'the app paused the task')
try {
ctx.on('agent/disposed', ({ agent }) => {
const id = String(agent?.id ?? '')
unwatch(id)
ruleConfigs.delete(id)
presets.delete(id)
})
ctx.on('dispose', () => {
for (const id of [...watching.keys()]) unwatch(id)
delete handlers['task-quiet']
delete handlers['task-stop']
delete handlers['task-cancel']
})
} catch {}
}