apsimo 1.3.0__py3-none-any.whl

apsimo/api/routers/commitment_work.py

@@ -0,0 +1,265 @@
+"""Explicit work coordination, with existing participant/writer authority."""
+from typing import Literal
+from contextlib import closing
+import hashlib
+import os
+from pathlib import Path
+import sqlite3
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, ConfigDict, Field, StrictBool
+from pydantic import field_validator
+
+from apsimo.api.authority import request_authority
+from apsimo.api.routers.executions import authorized_viewer
+from apsimo.commitments.work import CommitmentWork
+from apsimo.commitments.local_work import LocalWork, LocalWorkConflict
+
+router = APIRouter(prefix='/v1/host/commitments', tags=['commitments'])
+
+
+class WorkOperation(BaseModel):
+    model_config = ConfigDict(extra='forbid')
+    operation: Literal['claim', 'status', 'renew', 'release']
+    contact_id: str = Field(min_length=1, max_length=256)
+    session_id: str = Field(min_length=1, max_length=256)
+    task_id: str = Field(min_length=1, max_length=256)
+    turn_id: str = Field(min_length=1, max_length=256)
+    claim_id: str = Field(default='', pattern=r'^(?:[a-f0-9]{32})?$')
+
+
+@router.post('/{commitment_id}/work')
+def operate(commitment_id: str, body: WorkOperation, request: Request):
+    person, _ = authorized_viewer(request, body.contact_id, scope='turns:write')
+    from apsimo.api.routers import host
+    if host._commitment_store is None:
+        raise HTTPException(503, detail='commitment store unavailable')
+    try:
+        return CommitmentWork(host._commitment_store).operate(commitment_id,
+            **body.model_dump(exclude={'contact_id'}), contact_id=person,
+            principal_id=request_authority(request).principal_id)
+    except KeyError:
+        raise HTTPException(404, detail='unknown commitment') from None
+
+
+class LocalDraftHandoff(BaseModel):
+    model_config = ConfigDict(extra='forbid')
+    session_id: str = Field(min_length=1, max_length=256)
+    task_id: str = Field(min_length=1, max_length=256)
+    turn_id: str = Field(min_length=1, max_length=256)
+    claim_id: str = Field(pattern=r'^[a-f0-9]{32}$')
+
+
+class LocalDraftAcceptance(BaseModel):
+    model_config = ConfigDict(extra='forbid')
+    contact_id: str = Field(min_length=1, max_length=256)
+    session_id: str = Field(min_length=1, max_length=256)
+    turn_id: str = Field(min_length=1, max_length=256)
+    question: str = Field(min_length=1, max_length=2000)
+    sources: list[str] = Field(min_length=1, max_length=8)
+    origin: 'NativeDraftOrigin | None' = None
+    new_draft: StrictBool = False
+    handoff: LocalDraftHandoff | None = None
+
+    @field_validator('sources')
+    @classmethod
+    def explicit_paths(cls, value):
+        if (len(set(value)) != len(value)
+                or any(not Path(path).is_absolute() or len(path) > 4096 or '\x00' in path for path in value)):
+            raise ValueError('Distinct absolute local source paths are required')
+        return value
+
+
+class NativeDraftOrigin(BaseModel):
+    model_config = ConfigDict(extra='forbid')
+    platform: str = Field(min_length=1, max_length=64, pattern=r'^[a-z0-9_.-]+$')
+    chat_id: str = Field(min_length=1, max_length=512)
+    thread_id: str | None = Field(default=None, max_length=512)
+    user_id: str | None = Field(default=None, max_length=512)
+    user_id_alt: str | None = Field(default=None, max_length=512)
+    chat_type: str | None = Field(default=None, max_length=64)
+    notifier_profile: str | None = Field(default=None, max_length=256)
+
+
+LocalDraftAcceptance.model_rebuild()
+
+
+class NativeWorkRun(BaseModel):
+    model_config = ConfigDict(extra='forbid')
+    contact_id: str = Field(min_length=1, max_length=256)
+    native_job_id: str = Field(min_length=1, max_length=128)
+    native_execution_id: str = Field(pattern=r'^[a-f0-9]{32}$')
+
+
+class LocalDraftResult(BaseModel):
+    model_config = ConfigDict(extra='forbid')
+    status: Literal['draft_created', 'unavailable']
+    summary: str = Field(default='', max_length=1600)
+    report_path: str = Field(default='', max_length=4096)
+    report_sha256: str = Field(default='', pattern=r'^(?:[a-f0-9]{64})?$')
+    sources: dict[str, str] = Field(default_factory=dict, max_length=8)
+    model: str = Field(default='', max_length=256)
+    error_type: str = Field(default='', max_length=128, pattern=r'^[A-Za-z0-9_]*$')
+
+
+class NativeWorkFinish(NativeWorkRun):
+    result: LocalDraftResult
+
+
+class NativeTaskBinding(BaseModel):
+    model_config = ConfigDict(extra='forbid')
+    contact_id: str = Field(min_length=1, max_length=256)
+    native_board: str = Field(pattern=r'^[a-z0-9][a-z0-9_-]{0,63}$')
+    native_task_id: str = Field(min_length=1, max_length=128)
+
+
+class NativeKanbanRun(NativeTaskBinding):
+    native_run_id: int = Field(ge=1)
+    native_claim_lock: str = Field(min_length=1, max_length=256)
+
+
+class NativeKanbanFinish(NativeKanbanRun):
+    result: LocalDraftResult
+
+
+def accepted_native(body, initiative_id, person):
+    from apsimo.turns.hermes_kanban import task_snapshot
+    try:
+        # An accepted transition can wait briefly for a native writer, including
+        # Hermes' DELETE-journal fallback. Ordinary work projections stay fast.
+        return task_snapshot(initiative_id, person,
+                             body.model_dump(exclude={'contact_id', 'result'}), read_timeout=2.)
+    except (OSError, sqlite3.Error):
+        raise HTTPException(503, detail='native_board_unavailable') from None
+    except (ValueError, KeyError, TypeError) as error:
+        raise HTTPException(409, detail=str(error)) from None
+
+
+def local_store(request, contact_id, *, enabled=False):
+    person, owner = authorized_viewer(request, contact_id, scope='turns:write')
+    if not owner:
+        raise HTTPException(403, detail='owner_local_work_required')
+    if enabled and os.environ.get('COLONY_LOCAL_WORK_ENABLED', '').lower() != 'true':
+        raise HTTPException(503, detail='local_work_not_enabled')
+    from apsimo.api.routers import host
+    if host._initiative_store is None or host._commitment_store is None:
+        raise HTTPException(503, detail='local_work_store_unavailable')
+    return LocalWork(host._initiative_store, host._commitment_store), person
+
+
+def native_run(body, *, finishing=False):
+    from apsimo.turns.hermes_work import selected_home
+    home = selected_home()
+    if not home or body.native_job_id != os.environ.get('COLONY_LOCAL_WORK_JOB_ID'):
+        raise HTTPException(409, detail='selected_local_work_job_required')
+    home_id = hashlib.sha256(str(home).encode()).hexdigest()
+    def terminal(context):
+        if context.get('source_home_id') != home_id or context.get('native_job_id') != body.native_job_id:
+            return None
+        with closing(sqlite3.connect((home/'cron/executions.db').as_uri()+'?mode=ro', uri=True, timeout=.2)) as db:
+            row = db.execute('SELECT status FROM executions WHERE id=? AND job_id=?',
+                             (context.get('native_execution_id'), body.native_job_id)).fetchone()
+        return row[0] if row else None
+    native = {'source_home_id': home_id, 'native_job_id': body.native_job_id,
+              'native_execution_id': body.native_execution_id}
+    try:
+        status = terminal(native)
+    except (OSError, sqlite3.Error):
+        raise HTTPException(503, detail='native_execution_ledger_unavailable') from None
+    if status not in ({'running', 'completed', 'failed'} if finishing else {'running'}):
+        raise HTTPException(409, detail='running_native_execution_required')
+    return native, terminal
+
+
+@router.post('/{commitment_id}/local-draft')
+def accept_local_draft(commitment_id: str, body: LocalDraftAcceptance, request: Request):
+    return _accept_local_draft(commitment_id, body, request)
+
+
+@router.post('/local-draft')
+def accept_standalone_local_draft(body: LocalDraftAcceptance, request: Request):
+    return _accept_local_draft(None, body, request)
+
+
+def _accept_local_draft(commitment_id, body, request):
+    store, person = local_store(request, body.contact_id, enabled=True)
+    backend = os.environ.get('COLONY_LOCAL_WORK_EXECUTOR', 'cron')
+    if backend not in {'cron', 'kanban'}:
+        raise HTTPException(503, detail='local_work_executor_unavailable')
+    try:
+        return store.accept(commitment_id, **body.model_dump(exclude={'contact_id'}),
+                            contact_id=person, principal_id=request_authority(request).principal_id,
+                            execution_backend=backend)
+    except KeyError:
+        raise HTTPException(404, detail='unknown_commitment') from None
+    except LocalWorkConflict as error:
+        raise HTTPException(409, detail={'reason': str(error), 'initiative_id': error.initiative_id}) from None
+    except ValueError as error:
+        raise HTTPException(409, detail=str(error)) from None
+
+
+@router.post('/local-work/next')
+def next_local_draft(body: NativeWorkRun, request: Request):
+    store, person = local_store(request, body.contact_id, enabled=True)
+    native, terminal = native_run(body)
+    return {'assignment': store.select(person, native, terminal)}
+
+
+@router.get('/local-work/pending')
+def pending_native_drafts(contact_id: str, request: Request):
+    store, person = local_store(request, contact_id, enabled=True)
+    if os.environ.get('COLONY_LOCAL_WORK_EXECUTOR', 'cron') != 'kanban':
+        raise HTTPException(409, detail='native_execution_backend_required')
+    return store.native_pending(person)
+
+
+@router.post('/local-work/{initiative_id}/native-task')
+def attach_native_draft(initiative_id: str, body: NativeTaskBinding, request: Request):
+    store, person = local_store(request, body.contact_id, enabled=True)
+    native, _ = accepted_native(body, initiative_id, person)
+    try:
+        return store.attach_native_task(initiative_id, person, native)
+    except KeyError:
+        raise HTTPException(404, detail='unknown_local_work') from None
+    except ValueError as error:
+        raise HTTPException(409, detail=str(error)) from None
+
+
+@router.post('/local-work/{initiative_id}/native-run')
+def bind_native_draft(initiative_id: str, body: NativeKanbanRun, request: Request):
+    store, person = local_store(request, body.contact_id, enabled=True)
+    native, state = accepted_native(body, initiative_id, person)
+    try:
+        return store.bind_native_run(initiative_id, person, native, attempt_count=state['attempt_count'])
+    except KeyError:
+        raise HTTPException(404, detail='unknown_local_work') from None
+    except ValueError as error:
+        raise HTTPException(409, detail=str(error)) from None
+
+
+@router.get('/local-work/{initiative_id}')
+def local_draft_status(initiative_id: str, contact_id: str, request: Request):
+    store, person = local_store(request, contact_id)
+    try:
+        return store.status(initiative_id, person)
+    except KeyError:
+        raise HTTPException(404, detail='unknown_local_work') from None
+
+
+@router.post('/local-work/{initiative_id}/finish')
+def finish_local_draft(initiative_id: str, body: NativeWorkFinish | NativeKanbanFinish, request: Request):
+    store, person = local_store(request, body.contact_id)
+    native, _ = (accepted_native(body, initiative_id, person) if isinstance(body, NativeKanbanFinish)
+                 else native_run(body, finishing=True))
+    result = body.result.model_dump()
+    if result['status'] == 'draft_created':
+        if not result['report_sha256'] or not Path(result['report_path']).is_absolute() or not result['sources']:
+            raise HTTPException(422, detail='local_report_receipt_required')
+    elif not result['error_type']:
+        raise HTTPException(422, detail='failure_reason_required')
+    try:
+        return store.finish(initiative_id, person, native, result)
+    except KeyError:
+        raise HTTPException(404, detail='unknown_local_work') from None
+    except ValueError as error:
+        raise HTTPException(409, detail=str(error)) from None

apsimo/api/routers/context_gate.py

@@ -0,0 +1,123 @@
+"""Context-gate API: budget-aware context preparation for any agent.
+
+POST /v1/context/prepare — decide whether content fits a model's useful
+context window whole, and if not, chunk + retrieve (query-focused) or
+coverage-sample (holistic) down to budget. See
+:mod:`apsimo.contextgate` for the underlying machinery.
+
+Auth rides the global ApiKeyMiddleware like every other router.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import List, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from apsimo.contextgate import GateConfig, prepare_context
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/v1/context", tags=["context"])
+
+
+class DocumentIn(BaseModel):
+    name: str = ""
+    content: str
+
+
+class PrepareRequest(BaseModel):
+    content: Optional[str] = Field(
+        default=None, description="Raw text to prepare (or use `documents`)."
+    )
+    documents: Optional[List[DocumentIn]] = Field(
+        default=None, description="Named documents; concatenated with headers."
+    )
+    query: str = Field(
+        default="", description="The task/question the context will serve."
+    )
+    budget_tokens: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "Token budget. 0 = derive from `model_tier`'s usefulContextTokens, "
+            "else the COLONY_CONTEXT_GATE_BUDGET default."
+        ),
+    )
+    model_tier: str = Field(
+        default="",
+        description="small|medium|large — derive budget from this tier's config.",
+    )
+    task_kind: Optional[str] = Field(
+        default=None, description="retrieval | holistic (overrides the heuristic)."
+    )
+
+
+class PrepareResponse(BaseModel):
+    text: str
+    decision: str
+    task_kind: str
+    est_tokens_in: int
+    est_tokens_out: int
+    budget_tokens: int
+    chunks_total: int
+    chunks_used: int
+    coverage: float
+
+
+def _tier_budget(tier_name: str) -> int:
+    """Budget from the live LLMRouter's tier config (0 when unknown)."""
+    try:
+        from apsimo.api.routers.host import get_llm_router
+        from apsimo.router.tiers import ModelTier
+
+        llm_router = get_llm_router()
+        if llm_router is None:
+            return 0
+        cfg = llm_router.tier_config(ModelTier(tier_name))
+        return cfg.useful_context_tokens if cfg else 0
+    except (ValueError, ImportError):
+        return 0
+
+
+@router.post("/prepare", response_model=PrepareResponse)
+async def prepare(body: PrepareRequest) -> PrepareResponse:
+    """Prepare content to fit a model's useful context window."""
+    if body.content is None and not body.documents:
+        raise HTTPException(status_code=422, detail="Provide `content` or `documents`.")
+
+    if body.documents:
+        parts = []
+        for i, doc in enumerate(body.documents):
+            name = doc.name or f"document {i + 1}"
+            parts.append(f"# {name}\n\n{doc.content}")
+        content = "\n\n".join(parts)
+        if body.content:
+            content = body.content + "\n\n" + content
+    else:
+        content = body.content or ""
+
+    budget = body.budget_tokens
+    if budget <= 0 and body.model_tier:
+        budget = _tier_budget(body.model_tier.strip().lower())
+
+    prepared = await prepare_context(
+        content=content,
+        query=body.query,
+        budget_tokens=budget,
+        task_kind=body.task_kind,
+        config=GateConfig.from_env(),
+    )
+    return PrepareResponse(
+        text=prepared.text,
+        decision=prepared.decision.value,
+        task_kind=prepared.task_kind,
+        est_tokens_in=prepared.est_tokens_in,
+        est_tokens_out=prepared.est_tokens_out,
+        budget_tokens=prepared.budget_tokens,
+        chunks_total=prepared.chunks_total,
+        chunks_used=prepared.chunks_used,
+        coverage=prepared.coverage,
+    )

apsimo/api/routers/executions.py

@@ -0,0 +1,140 @@
+"""Execution observations reuse turn-writer and context-reader authority."""
+import os
+from typing import Literal
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from pydantic import BaseModel, ConfigDict, Field
+
+from apsimo.api.authority import request_authority, resolve_request_person
+from apsimo.turns.executions import registry
+
+router = APIRouter(prefix="/v1/host/executions", tags=["executions"])
+
+
+class ExecutionRuntimeObservation(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    event: Literal['start', 'response', 'error']
+    request_id: str = Field(default='', max_length=256, pattern=r'^[^\x00-\x1f]*$')
+    requested_model: str = Field(default='', max_length=256, pattern=r'^[^\x00-\x1f]*$')
+    provider: str = Field(default='', max_length=256, pattern=r'^[^\x00-\x1f]*$')
+    response_model: str = Field(default='', max_length=256, pattern=r'^[^\x00-\x1f]*$')
+    api_mode: str = Field(default='', max_length=256, pattern=r'^[^\x00-\x1f]*$')
+    profile_id: str = Field(default='', pattern=r'^(?:[a-f0-9]{64})?$')
+    runtime_kind: Literal['turn', 'cron', 'kanban_worker', 'delegated_child', 'unknown'] = 'unknown'
+    approx_input_tokens: int | None = Field(default=None, ge=0, le=2147483647)
+    max_tokens: int | None = Field(default=None, ge=0, le=2147483647)
+    output_limit_kind: Literal['request', 'provider_default', 'unknown'] = 'unknown'
+    tool_count: int | None = Field(default=None, ge=0, le=2147483647)
+    api_call_count: int | None = Field(default=None, ge=0, le=2147483647)
+    retry_count: int | None = Field(default=None, ge=0, le=2147483647)
+    started_at: float | None = Field(default=None, gt=0, allow_inf_nan=False)
+    ended_at: float | None = Field(default=None, gt=0, allow_inf_nan=False)
+
+
+class ExecutionInputReference(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    source_id: str = Field(min_length=1, max_length=256)
+    input_message_hash: str = Field(pattern=r'^[a-f0-9]{64}$')
+
+
+class ExecutionObservation(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    execution_id: str = Field(pattern=r"^[a-f0-9]{64}$")
+    contact_id: str = Field(min_length=1, max_length=256)
+    session_id: str = Field(min_length=1, max_length=256, pattern=r"^[^\x00-\x1f]+$")
+    turn_id: str = Field(min_length=1, max_length=256)
+    parent_execution_id: str = Field(default="", pattern=r"^(?:[a-f0-9]{64})?$")
+    platform: str = Field(min_length=1, max_length=64, pattern=r"^[a-z0-9_.-]+$")
+    state: Literal["observed", "completed", "failed", "interrupted", "ended"] = "observed"
+    phase: Literal["turn", "model", "tool", "between_calls", "ended"] = "turn"
+    tool_name: str = Field(default="", max_length=128, pattern=r"^[a-zA-Z0-9_.:-]*$")
+    sequence: int = Field(ge=1, le=2147483647)
+    runtime: ExecutionRuntimeObservation | None = None
+    # Exact already-admitted human inputs, never native task wrappers or titles.
+    input_refs: list[ExecutionInputReference] | None = Field(default=None, min_length=1, max_length=64)
+
+
+def authorized_viewer(request: Request, contact_id: str, *, scope: str) -> tuple[str, bool]:
+    authority = request_authority(request)
+    # Legacy body-selected identity is deliberately not sufficient for this new
+    # shared surface. Use the existing exact person grants, never an owner flag.
+    if not authority.authenticated or authority.anonymous or authority.legacy or not authority.has_scope(scope):
+        raise HTTPException(403, detail={"code": "scoped_execution_authority_required"})
+    person = resolve_request_person(request, claimed_person_id=contact_id)
+    owner = os.environ.get("COLONY_OWNER_PERSON_ID", "").strip() or os.environ.get("COLONY_OWNER_CONTACT_ID", "").strip()
+    return person, bool(owner and person == owner)
+
+
+@router.post("/observe")
+def observe(body: ExecutionObservation, request: Request):
+    person, _ = authorized_viewer(request, body.contact_id, scope="turns:write")
+    try:
+        return registry().observe(body.model_dump(), principal_id=request_authority(request).principal_id, contact_id=person)
+    except ValueError as exc:
+        raise HTTPException(409, detail={"code": str(exc)}) from exc
+
+
+@router.get("")
+async def active(request: Request, contact_id: str, session_id: str = "", limit: int = Query(20, ge=1, le=100),
+                 projection: Literal['full', 'request'] = 'full', input_context: bool = False):
+    person, owner = authorized_viewer(request, contact_id, scope="context:read")
+    if projection == 'request' and not owner:
+        raise HTTPException(403, detail='owner_work_context_required')
+    if projection == 'request':
+        limit = min(limit, 8)
+    view = registry().view(contact_id=person, owner=owner, session_id=session_id, limit=limit,
+                           include_ancestors=projection == 'request',
+                           include_inputs=projection == 'full' or input_context)
+    view = await with_queue_work(view, owner=owner, limit=limit)
+    if projection == 'request':
+        from apsimo.turns.executions import request_work_context
+        return request_work_context(view, limit=limit, session_id=session_id)
+    return view
+
+
+async def with_queue_work(view, *, owner, limit=8):
+    if not owner:
+        return view
+    import asyncio
+    from apsimo.turns.hermes_work import cron_view
+    from apsimo.turns.local_work import local_work_view
+    from apsimo.turns.hermes_kanban import kanban_view
+    from apsimo.turns.reported_workers import reported_worker_view
+    from apsimo.api.routers import host
+    from apsimo.turns.executions import work_source_coverage
+    import time
+
+    queue = getattr(host._task_queue, 'queue', host._task_queue)
+
+    async def read(reader, *, asynchronous=False, **reader_kwargs):
+        # These are independent read-only snapshots. One unavailable ledger
+        # must not hide work observed by all the other readers. Cancellation of
+        # a thread await does not stop its read; native readers bound SQLite work.
+        try:
+            operation = reader(limit=limit, **reader_kwargs) if asynchronous else asyncio.to_thread(reader, limit=limit, **reader_kwargs)
+            value = await asyncio.wait_for(operation, timeout=.2)
+            if value is None:
+                return None
+            return {**value, 'observed_at': time.time()}
+        except Exception:
+            return {'items': [], 'recent': [], 'available': False, 'unavailable': True,
+                    'reason': 'work_source_unavailable', 'observed_at': time.time()}
+
+    async def queue_view():
+        if queue is None or not callable(getattr(queue, 'current_work', None)):
+            return {'items': [], 'available': False, 'unavailable': True,
+                    'reason': 'queue_not_attached', 'source': 'canonical_task_queue'}
+        return await read(queue.current_work, asynchronous=True)
+
+    # All sources share the existing request budget, rather than each taking
+    # another sequential budget after the native ledgers finish.
+    view['native_cron'], view['local_work'], view['native_kanban'], reported, view['worker_work'] = await asyncio.gather(
+        # Leave executor/return slack for the multi-board reader to retain
+        # faster boards when its own partial-read budget is exhausted.
+        read(cron_view), read(local_work_view), read(kanban_view, read_budget=.15),
+        read(reported_worker_view), queue_view())
+    if reported is not None:
+        view['reported_worker'] = reported
+    view['work_sources'] = work_source_coverage(view)
+    view['coverage'] = 'registered Hermes turns and selected work ledgers; see work_sources for read coverage'
+    return view

apsimo/api/routers/followup_plans.py

@@ -0,0 +1,147 @@
+"""Exact prepared task configuration; permission remains at the private outbox."""
+import hashlib
+import json
+import time
+from contextlib import closing
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, ConfigDict, Field
+from typing import Literal
+
+from apsimo.api.authority import request_authority
+from apsimo.api.routers import temporal_followups as temporal
+from apsimo.commitments.work import CommitmentWork
+from apsimo.initiatives.temporal_followup import TemporalFollowups
+
+router = APIRouter(prefix='/v1/host/temporal-followups', tags=['commitments'])
+
+
+class FollowupPlan(BaseModel):
+    model_config = ConfigDict(extra='forbid', allow_inf_nan=False)
+    wait_id: str = Field(min_length=1, max_length=128)
+    commitment_id: str = Field(min_length=1, max_length=128)
+    work_id: str = Field(min_length=1, max_length=128)
+    source_id: str = Field(min_length=1, max_length=256)
+    source_version: str = Field(pattern='^[a-f0-9]{64}$')
+    recipient_id: str = Field(min_length=1, max_length=128)
+    channel: Literal['whatsapp', 'sms', 'rcs']
+    purpose: str = Field(min_length=1, max_length=512)
+    expires_at: float = Field(gt=0)
+    max_followups: Literal[1]
+    message: str = Field(min_length=1, max_length=8000)
+    message_sha256: str = Field(pattern='^[a-f0-9]{64}$')
+
+
+def digest(plan):
+    return hashlib.sha256(json.dumps(plan, sort_keys=True, separators=(',', ':'),
+        ensure_ascii=False).encode()).hexdigest()
+
+
+class BindPlan(BaseModel):
+    model_config = ConfigDict(extra='forbid')
+    contact_id: str
+    session_id: str
+    turn_id: str
+    claim_id: str
+    plan: FollowupPlan
+
+
+class CheckPlan(BaseModel):
+    model_config = ConfigDict(extra='forbid')
+    plan: FollowupPlan
+    outbound_ref: str = Field(min_length=1, max_length=256)
+    target: dict
+
+
+def _consistent(row, plan):
+    if any(row[key] != plan[key] for key in ('wait_id', 'commitment_id', 'work_id')):
+        raise ValueError('prepared_followup_task_mismatch')
+    if (row['contact_id'] != plan['recipient_id'] or row['expires_at'] != plan['expires_at']
+            or row['source_versions'].get(plan['source_id']) != plan['source_version']
+            or hashlib.sha256(plan['message'].encode()).hexdigest() != plan['message_sha256']):
+        raise ValueError('prepared_followup_evidence_mismatch')
+
+
+@router.post('/{wait_id}/bind-plan')
+def bind(wait_id: str, body: BindPlan, request: Request):
+    store, owner = temporal.ledger(request, body.contact_id, write=True)
+    def register():
+        row = temporal.owned(store, wait_id, owner)
+        plan = body.plan.model_dump()
+        _consistent(row, plan)
+        if not plan['source_id'].startswith('task-instruction:'):
+            raise ValueError('direct_owner_task_instruction_required')
+        if row['source_session_id'] != body.session_id:
+            raise ValueError('owner_task_session_mismatch')
+        existing = row['authority_scope']
+        if existing:
+            if existing.get('plan') != plan:
+                raise ValueError('task authority configuration is immutable')
+            return {'bound': True, 'plan_digest': digest(plan), 'effect_authorized': False}
+        current = CommitmentWork(store.store).operate(plan['commitment_id'], operation='renew',
+            principal_id=request_authority(request).principal_id, contact_id=owner,
+            session_id=body.session_id, task_id=plan['work_id'], turn_id=body.turn_id,
+            claim_id=body.claim_id)
+        if not current['accepted']:
+            raise ValueError('current_parent_work_claim_required')
+        store.bind_authority_scope(wait_id, scope={'plan': plan, 'plan_digest': digest(plan),
+            'owner_contact_id': owner, 'owner_evidence_ref': plan['source_id'],
+            'registered_at': time.time()}, evidence_ref=plan['source_id'])
+        return {'bound': True, 'plan_digest': digest(plan), 'effect_authorized': False}
+    return temporal.guarded(register)
+
+
+def _check(wait_id, body, request, *, require_coverage=False):
+    authority = request_authority(request)
+    if (not authority.authenticated or authority.anonymous or authority.legacy
+            or not authority.has_scope('transport:write')):
+        raise HTTPException(403, detail='trusted_transport_producer_required')
+    from apsimo.api.routers import host
+    if host._commitment_store is None:
+        raise HTTPException(503, detail='commitment_store_unavailable')
+    store = TemporalFollowups(host._commitment_store)
+    row = store.get(wait_id)
+    with closing(store.store._connect()) as db:
+        parent = db.execute('SELECT person_id FROM commitments WHERE id=?', (row['commitment_id'],)).fetchone()
+    if not parent:
+        raise ValueError('unknown_owner_task')
+    row = temporal.refresh_source_bindings(store, row, parent['person_id'])
+    if host._comms_log is not None:
+        from apsimo.api.routers.transport import reconcile_receipts
+        row = reconcile_receipts(store, host._comms_log, row)
+    plan = body.plan.model_dump()
+    _consistent(row, plan)
+    scope = row['authority_scope']
+    if (scope.get('plan') != plan or scope.get('plan_digest') != digest(plan)
+            or row['outbound_ref'] != body.outbound_ref
+            or body.target.get('channel') != plan['channel']):
+        raise ValueError('prepared_followup_binding_mismatch')
+    # Actual provider recipient/account/thread resolution and permission belong
+    # to the private policy/outbox. This proves the canonical task configuration.
+    check = store.preflight(wait_id)
+    current_sources = not temporal.source_bindings(row['source_refs'], row['source_versions'],
+        person=parent['person_id'], session_id=row['source_session_id'])
+    coverage = None
+    if require_coverage:
+        from .transport_ingress_api import followup_coverage
+        coverage = followup_coverage(principal=authority.principal_id, contact_id=row['contact_id'],
+                                     since=row['created_at'], channel=plan['channel'])
+        if not coverage['observed']:
+            check = {**check, 'review_allowed': False, 'reason': 'intake_coverage_unknown'}
+    return {'verified': current_sources and row['state'] not in {'cancelled', 'expired'},
+            'review_allowed': check['review_allowed'],
+            'reason': 'due' if check['review_allowed'] else check['reason'],
+            'plan_digest': digest(plan), 'owner_contact_id': scope['owner_contact_id'],
+            'owner_evidence_ref': scope['owner_evidence_ref'],
+            'registered_at': scope['registered_at'], 'resolved_contact_id': row['contact_id'],
+            **({'transport_coverage': coverage} if coverage is not None else {})}
+
+
+@router.post('/{wait_id}/verify-plan')
+async def verify(wait_id: str, body: CheckPlan, request: Request):
+    return temporal.guarded(lambda: _check(wait_id, body, request))
+
+
+@router.post('/{wait_id}/check-plan')
+async def check(wait_id: str, body: CheckPlan, request: Request):
+    return temporal.guarded(lambda: _check(wait_id, body, request, require_coverage=True))