Missions - Concierca AI

A mission is a step sequence (agents, human gates, waits, verifications, notifications, outbound HTTP calls) executed by the sequence engine. Missions are membership-scoped: you see and operate only missions where you are the owner or a member — never tenant-wide. Your role per mission is owner, lead, member or viewer; owner/lead may run and edit. Step types and their config contract (used by mission_create, mission_steps_update, mission_draft_update):

step_type	config
`agent`	`{agent_id, no_work_token?, require_receipts?}` — `no_work_token`: if the agent’s output ends with this exact token, the run completes silently (remaining steps skipped, no owner digest); `require_receipts`: an answer without a single tool call fails the step
`human`	`{approver_user_id?, instruction, kind: 'approve'\|'input'}`
`wait_time`	`{seconds}` or `{until_iso}`
`wait_poll`	`{interval_seconds, max_attempts, probe?}`
`verify`	`{probe: {kind: 'http'\|'db', ...}}`
`notify`	`{user_id?, message}`
`http_call`	`{url, method, headers?, body?, expect_status?, contains?, timeout?}` — outbound HTTP request; the response is checked against `expect_status` and/or `contains`; `timeout` is capped at 60s

Each step may also carry handoff_prompt, on_fail, and (in drafts) output_schema / step_key. Max 20 steps per mission. The 30 mission tools fall into six groups: reads (see a mission), diagnostics & analytics (understand a run), writes (edit the config), running & approving (execute + the human gate), runtime control (steer an active run, all human-gated), and drafts (stage edits before publishing).

Reads

`mission_list`

List the missions this user can see. Each row carries your role and the latest run.

Name	Type	Required	Description
`limit`	number	no	Max rows (default 50, max 200)

Returns: { projects: [...], count, note }. Each project row carries its core fields plus your role and last_run ({id, status, started_at, finished_at, total_credits} or null). Permissions: read; owner or member only.

{ "method": "tools/call", "params": { "name": "mission_list", "arguments": {} } }

`mission_get`

One mission in one read: core fields + your role, the business passport, a step summary, variables (metadata only — never secret values), the derived genome (structural fingerprint), capability manifest and version count.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { mission, passport, steps, variables, genome, manifest, version_count, note }. mission carries

id, role, name, goal, status, department_id, owner_user_id, created_at, updated_at, default_max_credits_per_run, max_cycles

plus a non-secret trigger: {schedule_enabled, webhook_enabled} (the raw trigger_config, including any webhook secret, is never exposed). steps is a summary ({position, step_type, step_key, has_output_schema}); variables is metadata only ({key, data_type, value_source, is_secret_reference}); passport is null when none is set. Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_get", "arguments": { "id": "<uuid>" } } }

`mission_status`

One mission’s full status: the step plan (positions + step_type + config) and the latest run with its per-step chain (status, attempts, timings) and total credits — same data as the app’s run timeline.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { project, steps, latest_run }. project is your access row; steps is the plan ({id, position, step_type, config, handoff_prompt, on_fail}); latest_run is

{id, status, started_by, total_credits, started_at, finished_at, steps: [{id, step_position, status, attempt_count, agent_run_id, started_at, finished_at}]}

or null when the mission has never run. Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_status", "arguments": { "id": "<uuid>" } } }

`mission_flow_get`

The mission’s full step plan (config, handoff_prompt, on_fail, output_schema, step_key) plus a preview subset for every referenced agent (name, model, tools/toolkits, data grants, skills, performance — never system prompts, credentials or secrets).

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { steps, agent_previews, note }. steps is the full plan ({id, position, step_type, step_key, config, handoff_prompt, on_fail, output_schema}); agent_previews is the membership-scoped preview subset for each referenced agent (name, model, tools/toolkits, data grants, skills, performance — never system prompts or secrets). Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_flow_get", "arguments": { "id": "<uuid>" } } }

`mission_members_get`

The mission roster: owner + members (user, name, role, since) and your own role. Membership is the mission’s visibility boundary.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { owner, members, your_role, note }. owner is {user_id, name, role:"owner"} (or null); members is [{user_id, name, role, since}]; your_role is your role on this mission. Permissions: read; owner or member only.

{ "method": "tools/call", "params": { "name": "mission_members_get", "arguments": { "id": "<uuid>" } } }

`mission_templates`

List the built-in mission templates (read-only catalog): slug, name, description, step chain and assignment slots (agent slots required, user slots optional). Instantiate one via mission_create with template_slug + assignments. Parameters: none. Returns: { templates, note }. Each template:

{slug, name, description, steps: [{position, step_type, agent_slot, user_slot}], agent_slots: [{key, label}], user_slots: [{key, label}]}

. Permissions: read.

{ "method": "tools/call", "params": { "name": "mission_templates", "arguments": {} } }

Diagnostics & analytics

`mission_run_trace_get`

Deep trace of one run: run header (status, business verdict, credits, budget) + the per-step chain (status, verdict, attempts, timings, agent version, capped receipt/input, cost/savings, tokens). Text fields are capped — this is a diagnosis surface, not a data dump.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`run_id`	string	yes	Run uuid (from `mission_status` or `mission_analytics_get.recent`)
`step_offset`	number	no	Pagination offset into the step chain (default 0)
`step_limit`	number	no	Steps per page (default 25, max 100)
`include_logs`	boolean	no	Include decision-log lines of the child agent runs
`include_artifacts`	boolean	no	Include artifact metadata (title/mime/size — no content)

Returns: { run, steps, step_count, page, logs?, artifacts?, note }. run is the run header (status, business_verdict, credits, budget snapshot/consumed/status). Each steps entry:

{step_position, step_type, status, business_verdict, attempt_count, agent_version, started_at, finished_at, instruction, receipt, agent_run}

— agent_run is {id, status, duration_sec, cost_usd, saved_usd, input_text, tokens_in, tokens_out} or null. page is {offset, limit, returned}. logs/artifacts appear only when the matching flag is set. Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_run_trace_get", "arguments": { "id": "<uuid>", "run_id": "<uuid>", "include_artifacts": true } } }

`mission_artifact_get`

Read one artifact a mission produced, with its content (spec, report, SOP, …). Get artifact ids from mission_run_trace_get with include_artifacts:true.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`artifact_id`	string	yes	Artifact uuid
`max_bytes`	number	no	Content cap in chars (default 20000, min 1000, max 100000)

Returns: { artifact, note }. artifact is {id, run_id, agent_id, title, mime, version, created_at, size, truncated, max_bytes, content} — size is the full char length, max_bytes the effective (clamped) cap actually applied, truncated true when size > max_bytes, and content the (possibly truncated) body. Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_artifact_get", "arguments": { "id": "<uuid>", "artifact_id": "<uuid>" } } }

`mission_analytics_get`

Aggregated analytics over the newest 200 runs — totals (success rate, avg duration, credits), per-step failure/duration/cost, recent runs, verdict-based analytics and reliability KPIs (retry rate, approval wait time). Same aggregation as the app’s Stats tab.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { totals, per_step, recent, analytics, reliability, window }. totals = success rate / avg duration / credits; per_step = per-position failure/duration/cost; recent = the 10 newest runs; analytics = verdict-based aggregation; reliability = retry rate / approval wait KPIs; window describes the run set used (e.g. "200 newest runs (max 200)"). Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_analytics_get", "arguments": { "id": "<uuid>" } } }

`mission_economics_get`

Mission economics over the newest 200 runs — total cost, realized savings, net value, ROI, profitable runs, per-day series. Same aggregation as the app’s Economics tab.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { economics, economics_series, window, note }. economics = total cost / realized savings / net value / ROI / profitable-run count; economics_series = the per-day series; window describes the run set. Cost is the stamped agent_runs.cost_usd; savings are stamped run snapshots (never recomputed). Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_economics_get", "arguments": { "id": "<uuid>" } } }

`mission_incidents_get`

Tenant-wide agent-run incident signal for the last 24h: total, failed, attributable failures, and the top affected mission. Aggregate counts only — no rows, no agent identity. Parameters: none. Returns: { total_24h, failed_24h, failed_24h_attributable, top_mission, note } — top_mission is {id, name, failed} (the mission with the most attributable failures) or null. Permissions: read.

{ "method": "tools/call", "params": { "name": "mission_incidents_get", "arguments": {} } }

`mission_validate`

Read-only pre-flight: checks mission active, agent steps assigned + active, human approver resolution, webhook secret, credit balance — plus a mocked happy-path walk through the sequencer and the derived capability manifest. Nothing is persisted, no agent runs.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { ok, checks, simulated_path, manifest, note }. ok is true only when every check passes; checks is [{name, ok, detail}] (mission active, agent steps assigned+active, human approver, webhook secret, credit balance); simulated_path is the ordered step positions of the mocked happy path; manifest is the derived capability manifest. Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_validate", "arguments": { "id": "<uuid>" } } }

`mission_compare_versions`

Diff two mission versions from the governance history: changed mission fields plus a per-position step diff (added/removed/type/agent/config/handoff changes).

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`version_a`	number	yes	Older version number
`version_b`	number	yes	Newer version number

Returns: { a, b, project_field_changes, step_diff, note }. a/b are {version, kind, actor, created_at} for each snapshot; project_field_changes lists which of name/goal/status/department_id differ; step_diff is {added_positions, removed_positions, changed: [{position, changes}]}. Snapshots are BEFORE-states with webhook secrets stripped. Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_compare_versions", "arguments": { "id": "<uuid>", "version_a": 3, "version_b": 5 } } }

`mission_compare_runs`

Two runs of the same mission side-by-side: run summaries (status, verdict, credits, total cost) and a per-position step comparison with a differs flag per step.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`run_a`	string	yes	First run uuid
`run_b`	string	yes	Second run uuid

Returns: { a, b, per_step }. a/b are run summaries ({id, status, business_verdict, started_at, finished_at, total_credits, total_cost_usd, steps}); per_step aligns the two runs by position: [{position, a, b, differs}] where each side is {status, verdict, attempts, duration_sec, cost_usd, agent_version} (or null) and differs flags a status/verdict/attempts/agent_version mismatch. Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_compare_runs", "arguments": { "id": "<uuid>", "run_a": "<uuid>", "run_b": "<uuid>" } } }

Writes

`mission_create`

Create a mission (you become owner + lead). Three modes:

Explicit steps — pass steps[], validated against the engine contract; agent steps may only reference agents visible to you.
AI wizard — pass goal text only; the wizard proposes a plan from your existing agents.
Template — pass template_slug + assignments (see mission_templates); every agent slot needs an agent uuid, user slots are optional.

Name	Type	Required	Description
`name`	string	with explicit steps	Mission name
`goal`	string	mode 2	Goal text — triggers the AI wizard when `steps` is omitted
`steps`	array	mode 1	`[{step_type, config, handoff_prompt?, on_fail?}]` (max 20)
`department_id`	string	no	Department uuid
`template_slug`	string	mode 3	Built-in template slug
`assignments`	object	mode 3	`{agents: {<slot>: '<agent uuid>'}, users?: {<slot>: '<user uuid>'}}`

Returns: { ok:true, project, steps, note }. project is the created mission row (id, name, goal, owner, …); steps echoes the resolved plan as [{position, step_type, config}]. Validation and mode errors return { error }. Permissions: write; creator becomes owner + lead.

{ "method": "tools/call", "params": { "name": "mission_create", "arguments": {
  "name": "Weekly lead digest",
  "steps": [
    { "step_type": "agent", "config": { "agent_id": "<uuid>" } },
    { "step_type": "human", "config": { "instruction": "Review the digest", "kind": "approve" } },
    { "step_type": "notify", "config": { "message": "Digest published." } }
  ]
} } }

`mission_update`

Merge-patch a mission — only supplied fields change (steps and members are never touched here). trigger_config is a section-level merge: schedule {enabled, cron '5-field', timezone} auto-starts runs on the cron; webhook {enabled, secret (16-128 chars)} makes POST /api/webhooks/inbound/<secret> start a run (the payload lands in run context). A paused mission never auto-starts.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`name`	string	no	Rename
`goal`	string	no	Goal text
`status`	string	no	`active` \| `paused`
`department_id`	string	no	Department uuid
`trigger_config`	object	no	`{schedule?, webhook?}` — only supplied sections change

Returns: { ok:true, project } — project is the patched row projected to {id, name, goal, status, department_id, owner_user_id}. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_update", "arguments": {
  "id": "<uuid>",
  "trigger_config": { "schedule": { "enabled": true, "cron": "0 9 * * 1", "timezone": "Europe/Zurich" } }
} } }

`mission_steps_update`

Edit the step plan of an existing mission. Actions: list (read the plan) · add (append one validated step) · update (merge-patch one step; config re-validated) · remove (delete one step) · reorder (bulk positions). Mutations are refused while a run is active.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`action`	string	no	`list` \| `add` \| `update` \| `remove` \| `reorder` (default `list`)
`step`	object	for `add`	`{step_type, config, handoff_prompt?, on_fail?}`
`step_id`	string	for `update`/`remove`	Step uuid (see action `list`)
`config`	object	for `update`	Replacement config (re-validated)
`handoff_prompt`	string	for `update`	Replacement handoff prompt
`on_fail`	object	for `update`	Replacement on-fail policy
`order`	array	for `reorder`	`[{id: '<step uuid>', position: 1}, ...]`

Returns: by action — list → { ok:true, steps: [{id, position, step_type, config, handoff_prompt, on_fail}] }; add → { ok:true, step, note } (the inserted row, appended at the end); update → { ok:true, step } (the patched row); remove/reorder → { ok:true }. Mutations while a run is active return { error }. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_steps_update", "arguments": {
  "id": "<uuid>",
  "action": "add",
  "step": { "step_type": "notify", "config": { "message": "Run finished." } }
} } }

`mission_members_update`

Add/update or remove a mission member. add upserts the member with a role (lead | member | viewer, default member); remove deletes them. The target user must belong to this tenant.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`action`	string	yes	`add` \| `remove`
`user_id`	string	yes	Target user uuid
`role`	string	no	Role for `add` (default `member`)

Returns: add → { ok:true, action:"add", member: {user_id, role} }; remove → { ok:true, action:"remove", user_id }. A user outside this tenant returns { error }. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_members_update", "arguments": {
  "id": "<uuid>", "action": "add", "user_id": "<uuid>", "role": "member"
} } }

Running & approving

`mission_run`

Start a run of the mission’s step sequence. At most one active run per mission — starting while a run is active returns a clean conflict error. Track progress with mission_status.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { ok:true, project_run_id, note }. Starting while a run is active returns a conflict { error, status }. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_run", "arguments": { "id": "<uuid>" } } }

`mission_approve_step`

Decide the mission’s currently awaiting human step (approve or reject). This is the human gate — only call it when the human user explicitly decided. Reject stops the run.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`decision`	string	yes	`approve` \| `reject`
`input`	string	no	Optional human input passed to the step (`kind:'input'`)

Returns: { ok:true, project_run_id, decision, run_status? } — decision echoes approve/reject; run_status is present when the decision changed the run’s lifecycle. Permissions: write; the step’s designated approver, the mission owner, or a lead member.

{ "method": "tools/call", "params": { "name": "mission_approve_step", "arguments": { "id": "<uuid>", "decision": "approve" } } }

Runtime control (human-gated)

All four tools follow the same pattern: call without confirm first to get a would block (mission name, run id, run status, effect); show it to the human; re-call with confirm:true only once they decided.

`mission_cancel`

Cancel the currently active run. The running step finishes, then the chain stops. Terminal — a canceled run can never be resumed (use mission_pause if you want it resumable). Returns “No active run for this mission” when nothing is running.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`confirm`	boolean	no	Must be `true` to actually cancel

Returns: without confirm → { error, requires_confirmation:true, would, note } (nothing changed); with confirm:true → { ok:true, project_run_id, status:"canceled" }. No active run → { error: "No active run for this mission" }. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_cancel", "arguments": { "id": "<uuid>", "confirm": true } } }

`mission_pause`

Pause the currently active run. The running step finishes, then nothing further dispatches — reversible with mission_resume. Only a running run can be paused.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`confirm`	boolean	no	Must be `true` to actually pause

Returns: without confirm → { error, requires_confirmation:true, would, note }; with confirm:true → { ok:true, project_run_id, status:"paused" }. Only a running run can be paused. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_pause", "arguments": { "id": "<uuid>", "confirm": true } } }

`mission_resume`

Resume the paused run: it flips back to running and continues from the first non-success step, never from the top. Only a paused run can be resumed.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`confirm`	boolean	no	Must be `true` to actually resume

Returns: without confirm → { error, requires_confirmation:true, would, note }; with confirm:true → { ok:true, project_run_id, status:"running" }. Only a paused run can be resumed. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_resume", "arguments": { "id": "<uuid>", "confirm": true } } }

`mission_budget_increase`

Raise the active run’s credit budget by add_credits (integer 1–1000). Audited (who, role, old/new cap, reason) and optimistically locked — a concurrent top-up returns a retry conflict. If the run was parked on a budget block, the raise clears it and the sequence resumes (resumed in the response). Spends real credits.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`add_credits`	number	yes	Credits to add (integer, 1–1000)
`reason`	string	no	Justification, stored in the audit trail
`confirm`	boolean	no	Must be `true` to actually raise the budget

Returns: without confirm → { error, requires_confirmation:true, would, note } (the would block includes add_credits and reason); with confirm:true → { ok:true, project_run_id, budget, resumed } — budget is the new cap and resumed is true when the raise cleared a budget block and the sequence continued. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_budget_increase", "arguments": {
  "id": "<uuid>", "add_credits": 50, "reason": "Long research run", "confirm": true
} } }

Drafts (staged edits)

A draft is a pending copy of the mission config (name/goal/department + full step list). Runs keep using the published config until the draft is published.

`mission_draft_get`

Get the mission’s pending draft, or null when none exists.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { draft } — the pending draft object (name/goal/department + full step list, with base_version), or { draft: null } when none exists. Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_draft_get", "arguments": { "id": "<uuid>" } } }

`mission_draft_create`

Cut a draft from the current live config. Fails if a draft already exists (update or discard it first).

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { draft } — the newly cut draft. If one already exists → { error, code } (update or discard it first). Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_draft_create", "arguments": { "id": "<uuid>" } } }

`mission_draft_update`

Merge-patch the draft: mission fields and/or a full replacement step list (max 20, same engine contract and agent-visibility gate as mission_create). Steps may carry output_schema / step_key. Nothing is published.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`project`	object	no	`{name?, goal?, department_id?}` — only supplied fields change
`steps`	array	no	Full replacement plan `[{step_type, config, handoff_prompt?, on_fail?, output_schema?, step_key?}]`

Returns: { draft } — the merged draft after the patch. Validation failures (bad step, invisible agent) → { error }; conflict → { error, code }. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_draft_update", "arguments": {
  "id": "<uuid>",
  "project": { "goal": "Refined weekly digest" },
  "steps": [ { "step_type": "agent", "config": { "agent_id": "<uuid>" } } ]
} } }

`mission_change_proposal_preview`

What would publishing the current draft change? Diffs the draft against the live mission: per-field changes and added/removed/modified steps (with the exact step fields that differ). Also flags a stale draft — one cut before someone else published. Read-only.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { has_changes, stale, base_version, current_version, diff, note }. diff holds per-field changes and added/removed/modified steps; stale:true means the mission changed since the draft was cut (publishing would overwrite that change). No draft → { error }. Permissions: read; membership-scoped.

{ "method": "tools/call", "params": { "name": "mission_change_proposal_preview", "arguments": { "id": "<uuid>" } } }

`mission_draft_discard`

Discard the pending draft — staged changes are lost, the live mission is untouched.

Name	Type	Required	Description
`id`	string	yes	Mission uuid

Returns: { ok:true } on discard; { error, code } if there was nothing to discard. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_draft_discard", "arguments": { "id": "<uuid>" } } }

`mission_draft_publish`

Publish the draft onto the live config: the before state is version-captured, then the mission fields + step list are replaced and the draft is cleared. Refuses while a run is active, and refuses a stale draft unless force:true.

Name	Type	Required	Description
`id`	string	yes	Mission uuid
`force`	boolean	no	Publish even if the draft is stale (overwrites newer live edits)

Returns: { ok:true, published_version } — the new live version number after the draft’s fields + step list replaced the live config and the draft was cleared. Refused while a run is active, or on a stale draft without force:true → { error, code }. Permissions: write; owner or lead only.

{ "method": "tools/call", "params": { "name": "mission_draft_publish", "arguments": { "id": "<uuid>" } } }

​Reads

​mission_list

​mission_get

​mission_status

​mission_flow_get

​mission_members_get

​mission_templates

​Diagnostics & analytics

​mission_run_trace_get

​mission_artifact_get

​mission_analytics_get

​mission_economics_get

​mission_incidents_get

​mission_validate

​mission_compare_versions

​mission_compare_runs

​Writes

​mission_create

​mission_update

​mission_steps_update

​mission_members_update

​Running & approving

​mission_run

​mission_approve_step

​Runtime control (human-gated)

​mission_cancel

​mission_pause

​mission_resume

​mission_budget_increase

​Drafts (staged edits)

​mission_draft_get

​mission_draft_create

​mission_draft_update

​mission_change_proposal_preview

​mission_draft_discard

​mission_draft_publish