Mothership

Runtime and automation

Runtime carries a planner-and-tools loop in the background from a profile the app declares, and waits for a person before risky tools. Automation reaches the same execution path from schedules, events and webhooks.

Runtime

Declare runtime_profiles in the app's manifest. Runs go into a durable queue and a separate runtime_worker executes them, so they continue after the browser disconnects.

jsonc
"runtime_profiles": [{
  "id": "review-loop",
  "model_profile": "smart",             // the AI tier that plans
  "tool_set": ["document.classify"],    // capabilities used as tools (connectors: connector:<id>/<tool>)
  "procedure": "react",                 // or "plan-execute"
  "skill_policy": {},
  "system_instruction": "You review documents.",
  "max_iterations": 8
}]
ts
const run = await ctx.api.runtime.start({ profile: "review-loop", input: { question: "Summarize the report" } });
for await (const event of ctx.api.runtime.subscribe(run.runId, { transport: "sse" })) {
  // run.*, planner.iteration.completed, tool.started|completed, job.linked, output.delta|completed
}
  • Start and resume return 202 with a queued snapshot. Events are numbered, so a subscriber resumes where it left off (polling by default, SSE optional).
  • People in the loop: risk_class: "high" tools always wait for approval. Input requests (decision: "submit" with an input matching the schema) and consent (approve / deny) work the same way. Consent never grants extra tool permissions.
  • skill_policy: deny_tools, require_approval, max_tool_calls, allow_ask_user, allow_consent, interrupt_ttl_seconds. Unknown fields are refused.
  • Between steps the worker re-checks company, membership, claims, release, profile and deployment credentials. A crash at a safe checkpoint resumes; a crash with an external tool's outcome unknown fails as runtime_execution_uncertain instead of replaying it.

Jobs and streams

A backend worker's kind: "job" operations report progress and completion through callbacks after :start. At most once, no automatic retry. Concurrency is capped by usage_policy.limits (global, per company, per person). kind: "stream" operations pass the worker's SSE through.

Automation

Declare schedule, event and webhook triggers as trigger_templates in the manifest; the app creates instances. A trigger fires through the same execution path as a direct call, allowlists, claims and concurrency caps included.

jsonc
"trigger_templates": [{
  "id": "nightly-classify",
  "source": { "type": "schedule", "interval_seconds": 86400 },
  "target": { "type": "capability", "id": "document.classify", "version": "1.0" },
  "run_as": "user_delegated",           // or "agent_service"
  "delivery": "at_least_once",
  "configurable_fields": ["interval_seconds"],
  "retry": { "max_attempts": 2, "backoff_seconds": 60 },
  "concurrency": "forbid"
}]
Source How it fires
Schedule interval_seconds. No cron expressions or calendars yet
Event POST /api/v1/automation/instances/{id}/events with an app token
Webhook POST /api/v1/automation/instances/{id}/webhook with X-Mothership-Signature: sha256=<HMAC> (over timestamp, event ID, trigger ID and body) and a timestamp within 300 seconds

The run_triggers worker delivers them (it is part of the production workers). Every attempt for one event carries the same Idempotency-Key; receivers must honour it to avoid duplicate effects.

Esc