Skip to main content

Assignments

An assignment is a goal the bot keeps working on across days until it is met, abandoned or out of budget. It works in short runs called wakes, keeps notes in a scratchpad you can read, hands steps to you, and stops on its own. In chat you can call it a quest, an errand or a mission; commands, files and notices always say assignment.

A single task already has compaction, !steer, !stop, retries and a turn limit. An assignment adds what a single task cannot hold: state that lives outside any one context window, a lifetime of days with no worker held while it waits, a budget across all its runs, steps that belong to you rather than the bot, and progress judged by the host from evidence the model cannot write.

Who can use it​

Assignments are on by default and for admins only. A non-admin gets not_admin from every command and has no Assignments section in Settings. An admin who loses admin keeps any running assignment running, the same as a scheduled job, and can no longer change it.

Starting one​

You describe the goal in your private web or Talk chat, and the bot turns it into a charter with the assignment skill. The charter is:

  • a title and a goal;
  • what the bot may do without asking (the autonomy clause), stated as actions and recipients, such as "may email the installers on the approved list about quotes";
  • done-when items, each either mechanical (a check the host runs on a file) or confirmed (you tick it);
  • frozen commitments, values only you can change, such as a price ceiling;
  • a budget in list-price dollars and a number of wakes, plus per-wake limits in minutes and turns;
  • an optional deadline and a check-in interval (the cadence, 6 hours by default).

After each change the bot shows you the charter as rendered text. When you are happy, say so; the bot runs activate, and you are asked to approve that exact text. Approval is the one approval an assignment needs: spending starts there. Any change to the charter while the approval is waiting cancels it, so what you approve is always what you read.

After activation, charter changes you make in chat apply at once, and the next wake is told what changed. Raising the budget is a top-up.

Only your own turn in your private chat can change the charter, activate, pause, resume, wake, top up, abandon, close, leave a note or report a step done. Email, SMS, WhatsApp, scheduled jobs, shared rooms and the wakes themselves cannot. The Assignments page can do everything on that list but change the charter and activate.

Mechanical checks​

A mechanical item names a file in the assignment's folder and one of three checks:

CheckPasses when
file_parsesThe file is a regular file of at most 1 MiB and parses as CSV, JSON, TOML or non-empty UTF-8 markdown
csv_columnsThe CSV has every named column, no blank value in them, and at least the minimum number of data rows
containsThe file contains a literal piece of text, or does not when the item says so

The host runs every check after every wake. A link in the folder is not followed, so a check never reads outside it.

What happens while it runs​

The scheduler wakes an assignment when its next wake is due, when you leave it a note, report a step done or confirm an item, and once at the deadline. A completion it proposed holds the deadline wake back until you answer it: confirming closes the assignment, and rejecting it lets the deadline wake run, if the deadline has not had one. A wake is an ordinary task on its own worker lane: its prompt carries the charter, the done-when board, open hand-offs, what arrived since the last wake, the attempt log, the scratchpad and the last wakes' summaries. Its answer is not posted anywhere; it is kept as the wake's summary.

A wake ends by asking for the next one: in some hours, at a time, or not until you act. It can hand you a step ("photograph the furnace label", with what to report back and a due date), record what it tried and how it went, report a milestone, and propose completion. Two wakes are at least 15 minutes apart by default.

The folder and the scratchpad​

Each assignment has a folder at <bot folder>/assignments/<slug>/ in your files. CHARTER.md there is generated from the record; editing it changes nothing. SCRATCHPAD.md holds the bot's notes, with sections for what it is doing now, what is done, its thinking, what it rejected, problems and findings.

To steer an assignment, leave it a note (assignment note, or Note on its page), which the next wake reads as your words. Editing the scratchpad does not steer it. Any of your tasks can write that file, including one started by an email, a scheduled job or a turn in a shared room, so the bot cannot tell your change from theirs. The next wake is shown a change made outside a wake as untrusted material with its source unknown, never as your instruction, and a wake is free to remove those lines. A scratchpad that is missing, emptied or unreadable is restored from the last good copy. Every version is kept in the database, so a bad line can be traced to the wake that wrote it.

Progress, pauses and completion​

The host decides whether a wake made progress, from things the model cannot fake: a check that newly passes, a confirmed item, input from you, a step you reported done, an attempt with an outcome not seen before, or a deliverable that changed and passes its checks. Scratchpad edits alone never count.

The host pauses an assignment, and tells you why, when:

  • the budget is spent, before a wake starts or after one ends;
  • three wakes in a row made no progress (stalled);
  • three wakes in a row failed;
  • one step failed four times in a row (after three, the next wake is told to try another way or hand it to you);
  • the deadline wake ended without completing it.

A pause you set yourself waits for you to resume it. A wake running when you pause or abandon finishes, and your state stands.

When a wake proposes completion, the host runs every check first. If any mechanical item fails, the proposal is refused and the next wake is told which items. Otherwise the assignment completes on its own if the charter allows that and nothing is left to confirm; if not, it waits for you to confirm it or say what is missing.

You can also finish it without a wake. Confirming the last item you were asked to confirm completes the assignment when every mechanical check passes at that moment, since your confirmation is the answer a proposal would ask for. close --completed does the same when nothing has been proposed, from a sleeping assignment or one waiting on you, and names the failing items if any check fails.

Notices​

What needs you reaches the notifications bell, under the push category "Assignments". Routine wakes post nothing.

NoticeWhenClears when
A step for youA wake hands you a stepYou report it done
PausedThe host pauses it (budget, stalled, failures, a repeated failure, deadline)It is resumed, topped up or abandoned
Says it is doneA wake proposes completion and it waits for youYou confirm it or say what is missing
Budget running low75% of the dollar or wake budget is spentIt is topped up or ends
Progress reportA wake reports a milestoneYou see it
CompletedIt completesYou see it

Each notice in the bell starts with the assignment's number and slug (Assignment 1 · heat-pump-quotes), so you can name it in chat. It has three links: Open assignment goes to its page in Settings, Open in chat goes to the room you activated the assignment from, or your default room when that one is gone or you have left it, and Open folder opens the assignment's folder on the Files page.

A notice's text may quote what a wake wrote, such as the step or the report, and that text stays in the bell. A push names the assignment and points to the bell. When you confirm completion yourself, in chat or on its page, the completed notice goes to the bell without a push.

The Assignments page​

Settings, Assignments shows your assignments and lets you steer them without opening chat. They are still started and changed in chat: the page cannot create one, change its charter or activate it, and a draft's page links back to chat.

The list has the active assignments, drafts included, each with its state, its next wake or what it waits on, the budget used and any open hand-offs. Finished ones are in a closed group below them. An assignment's own page has these parts:

PartWhat it has
NowThe state and why, when it wakes and the deadline, with Pause, Resume, Wake now and Abandon where the state allows them. A proposed completion shows its evidence, with Complete and Send back
Hand-offsEach open step, with a report field and Mark done
Done whenEach item and its status, and Confirm on an item you were asked to confirm
BudgetCost and wakes against their limits, wakes that could not be measured, and Top up
NoteA field for a note, which the next wake reads as your words
CharterThe goal, what it may do without asking, frozen commitments and the deadline, read only, with Open folder
Recent wakesUp to 20 wakes: when, what started each one, how it ended, its cost and its summary
Network accessThe hosts and skills it may use, while it is not finished

Text a wake wrote is shown as plain text, so a link or markup in it does nothing. It may quote a web page or a mail, so read it as you would that source.

Dollars here are list-price dollars, the unit a charter's budget is set in, and not what you were billed. A budget pause has no Resume, because a top-up is what ends it. A top-up too small to end the pause says it is still paused, with what is left and what its cheapest wake has cost.

The page reads again after each action and when you come back to the tab. If the assignment skill is disabled for you, the section is hidden and a link to the page says assignments are not available.

Budget and cost​

The dollar budget is counted from the usage records of the assignment's wakes, which the model cannot write. A wake whose cost could not be measured counts as zero; show says how many there were, and the wake cap still binds. Tokens are recorded but not limited. The budget can be overshot by at most one wake, since a running wake is not stopped for cost. To keep that rare, the host does not start a wake when less is left than the cheapest measured wake of this assignment has cost; the assignment pauses for budget instead, and a top-up must leave at least that much to resume it; topup says so when it does not. Before any wake has been measured there is no such floor.

Each wake's time limit is the charter's per-wake minutes, never past task_timeout_minutes. The per-wake turn limit applies on the native brain only.

Commands​

All verbs are istota-skill assignment <verb>, normally run by the bot for you. <id> is the number or the slug.

From your own turn: create, set, item add|remove|confirm, frozen add|remove, activate, pause, resume, abandon, wake, topup --usd N | --wakes N, note, handoff done <id> <action-id> --report, and close --completed | --reject "what is missing". From any task of yours: list and show. From a wake, on its own assignment only: next, handoff, report, attempt and complete.

show and the replies of the other verbs include wake_due: why the scheduler will wake the assignment on its next pass (inbox, time or deadline), or empty when it will not. An assignment waiting on you that shows inbox has already been answered and is about to wake.

Errors are {"status": "error", "error": "<code>", "message": "..."}:

CodeMeaning
feature_disabledThe assignment skill is disabled for this user or unavailable on this deployment
not_adminThe caller is not an admin
not_foundNo such assignment, item, hand-off or frozen commitment for this user
not_a_user_turnThe verb needs your own turn in your private chat, or the task has restricted reach (a guest's or correspondent's turn, a public job, or a task nobody asked in a shared room)
not_a_wakeA wake-only verb from something other than a running wake
wrong_assignmentA wake named another assignment
bad_stateNot allowed in the current state, which the error names
not_metclose --completed with nothing proposed, while a mechanical check fails; the message names the items
items_changedThe assignment or its done-when list changed while close was checking it; run it again
over_ceilingA budget above the deployment's ceiling
too_many_activeThe user is at the limit of running assignments
invalid_charterA charter field is missing or not valid
invalid_validatorA mechanical check is not valid
invalid_durationA duration is not Nm, Nh or Nd
invalid_inputAnother argument is not valid
deadline_passedThe deadline has already passed
confirmation_pendingAn approval for this assignment, or for this turn, is already waiting
task_unavailableThe calling task is not running

An approval that cannot start the assignment closes with one of charter_changed (the charter changed since it was shown), bad_state, deadline_passed, too_many_active, not_found or assignment_unavailable, and the waiting task is cancelled.

Configuration​

Deployment limits, in [assignments]:

KeyDefaultWhat it sets
max_workers2Assignment wakes running at once across the instance
user_max_workers1Assignment wakes one user may run at once
max_active_per_user3Assignments past draft and not yet closed, per user
max_cost_usd_per_assignment50.0Ceiling on any charter's dollar budget
max_wakes_per_assignment500Ceiling on any charter's wake budget
min_wake_interval_minutes15Shortest gap between two wakes of one assignment
stall_wakes3Wakes in a row with no progress before a pause
failure_wakes3Failed wakes in a row before a pause
budget_low_fraction0.75Share of the budget spent that raises the low-budget notice
scratchpad_prompt_chars24000Scratchpad cap in a wake's prompt
history_prompt_chars12000Cap on earlier wake summaries in a wake's prompt

Limits​

  • One owner per assignment. No shared or group assignments.
  • No assignment room, questions, watchers, detached jobs or child tasks yet; you steer with notes, the page and the commands above.
  • A wake uses the existing skills under their existing gates. Held outbound mail, relay approval and Wallet policy apply as they do to any task.
  • A save to the scratchpad while a wake is running is attributed to the wake.
  • Nothing deletes an assignment. A completed or abandoned one keeps its rows, files and ledger.

Upgrading​

The first start adds the assignment tables and two columns, and rebuilds the request ledger table to allow the activation request. The rebuild is a migration covered by the upgrade tier (scripts/test-upgrade.sh).