Journey: Agentic pipeline customer invocation

Journey flow#

Generated from the authored steps below — click a node to jump to that section.

The end-to-end shape of any one of the seven registered Cross-Domain Autonomous Pipelines — from "the customer (or scheduler) hit Run" to "the operator queue clears, the customer reads the output, the audit log closes." Use this single template against each pipeline variant; the per-pipeline differences (trigger surface, agent backbone, output schema, approval gate, customer-facing entry) are listed in the "Pipeline variants" table at the end.

Personas#

• Customer — consenting user whose data / topic anchor seeds the run; customer-tier pipelines (arete.weekly_review_draft, metis.course_from_byom, nisaba.edition_study_guide) are invoked directly; operator-tier pipelines (veritas.story_drafting, tara.seasonal_program, nyx.event_explainer_set) run on the customer's behalf
• Tenant scheduler — cron-fires recurring pipelines per tenant policy
• Pipeline orchestrator — @oshun/agentic-studio dispatcher; resolves registry → plan DAG → sub-agent hand-offs
• Lilith tone reviewer agent — lilith.tone-reviewer; mandatory pre-check
• Domain sub-agents — vary by pipeline (see variants table)
• Reviewer — operator-studio editor / tenant-teacher / scholar-tier / user-self (varies by pipeline's final approval gate)

Pre-conditions#

• Pipeline is registered in V1_PIPELINES (libs/oshun/agentic-studio/src/pipelines/v1-pipelines.ts) with lifecycleState: 'live'
• Invoker's tier matches the pipeline's invocationTier
• Tool grants resolve cleanly via libs/oshun/agent-pipelines/src/grants/resolver.ts (none revoked / expired)
• mandatoryApprovalGateIds have a seated reviewer for the invoker's (tenant, domain, tone-class) triple
• Customer-tier: consent flags on the underlying data scope (Iris memory, journal, habits) are current
• Operator-tier: operator's authoring session is on /operator/studio

Steps#

1. Trigger / origin#

The registry permits three origins. The shipped customer UI currently proves the explicit Run Now path for arete.weekly_review_draft; the remaining surface and scheduler origins stay unchecked until their adapters are wired.

• Push notification — customer taps a system push (e.g., "Your weekly review is ready"); deep-link payload carries ?pipeline=<id>&run_intent
• Explicit Run Now button — the Arete weekly-review draft uses the real lifecycle from /arete/review; other variants remain as stated in the table
• Scheduled cron — tenant scheduler fires per PipelineSchedule (nextFireFor in @oshun/agentic-studio)
• BFF receives the trigger (customer-tier: apps/oshun/bff/src/<domain>/; operator-tier: apps/oshun/bff/src/admin/ via admin-agentic-operations-store.ts)
• Telemetry: agentic_pipeline_triggered (pipelineId, trigger_origin, invoker_id, tenant_id)

2. AgentRun row + envelope created#

• Dispatcher resolves pipelineId against PipelineRegistry; rejects lifecycleState: 'deprecated' cleanly
• effectivePipelineForTenant() applies tenant PipelineCustomization (budget cap, approval gates, lineage overrides)
• Fresh AgentRun row written per libs/contracts/src/common/agent-run.ts (inputs, plan, tool-calls, intermediate-artifacts, evidence, cost-ledger, decision-rationale, output-bundles, status, provenance)
• State: pending → planning on dispatch
• Verify: [operator/operator-admin.md](../operator/operator-admin.md) admin inbox shows the new run with runId, pipelineId, state

3. Lilith policy pre-check (tone + crisis screens)#

• Dispatcher calls lilith.tone-reviewer against seed inputs (topic anchor, BYOM bundle, mood signal, ephemeris anchor, etc.)
• Lilith returns (allow | reduced | suppress) plus a crisis-frame directive
• suppress → run failed with lilith.suppressed; trigger surface shows a soft handoff (Tara breath, Arete journal)
• reduced narrows audacity / tone-band ceiling on every downstream sub-agent dispatch; allow proceeds to executing
• Verify: [journeys/crisis-aware-tone-policy.md](./crisis-aware-tone-policy.md) for the suppress branch end-to-end

4. Tool execution loop (sub-domain hand-offs)#

The plan DAG (PlanDag from @oshun/agentic-studio/plans/plan-dag) iterates its stages; each stage dispatches sub-agents under the parent's budget/authority envelope.

• Stage 1..N dispatch against participatingAgentIds with sub-budgets deducted from totalBudgetCap
• Authority envelope narrows or matches parent (never widens; enforced by grants/resolver.ts)
• Grounded-composition stages call sophia.ground (retrieve → rank → ground → cite); Isis-emitted artifacts call generate.* and return a ProvenanceBundle ref with the output
• Verify: [journeys/sophia-grounded-answer.md](./sophia-grounded-answer.md) for the retrieval-augmented composition path
• Every tool call appended to AgentRun.toolCalls[] with (toolId, scope, capabilityModifiers, costUnitsUsed, ts)
• Budget overshoot → subagent_budget_exceeded; parent retries without the tool or fails fast
• Depth cap (default 5) prevents runaway chains; cycle prevention rejects ancestor re-entry unless allow_cycle=true at root

5. Provenance trail accumulates (Isis hash chain)#

• Each generated artifact's ProvenanceBundle carries the attribution chain (rootAgent → ... → producingAgent) plus consent, prompt, model, workflow, watermark, timestamp; bundle hash-chained to the previous artifact in the run (see WALKTHROUGH/studio/domain-bridges/isis/)
• Verify: [journeys/citation-drift-resolution.md](./citation-drift-resolution.md) for the hash-chain inspection flow
• Per-stage event log captures every dispatch, terminal state, and unused-budget return

6. Output assembly#

• Final stage assembles the per-pipeline output schema (see variants table; matches expectedOutputSchemaNames)
• Output bundle written to AgentRun.outputBundles[] with provenance ref
• buildPipelineObservabilityReport records per-stage SLA, evidence completeness, human-touch points
• detectPipelineDeviation checks declared (participatingAgentIds, expectedHandoffDepth, totalBudgetCap) envelope; deviations route to operator review

7. Author review queue (gated)#

State enters awaiting_approval until the gate clears.

• Run appears in the gate's reviewer queue (operator-studio editorial / scholar-tier / tenant-teacher / user inbox)
• Verify: [journeys/editorial-review-approval.md](./editorial-review-approval.md) for the operator review and decision flow
• Reviewer surfaces include the full AgentRun envelope (plan, tool-calls, evidence, provenance) — no black-box approval
• Reviewer can approve (completed), request changes (loops back to executing), or deny (killed with reason)
• mandatoryApprovalGateIds cannot be bypassed by tenant policy

8. Customer notification + entry point#

• On completed, notify.send dispatches per quiet-hours and channel preferences (push, email, in-app)
• Notification copy pipeline-specific; deep-link carries ?run=<runId> to the per-pipeline customer surface
• Quiet hours defer (not lose) per Iris policy
• Telemetry: agentic_pipeline_notification_sent / ..._notification_clicked

9. Customer reads, can approve / edit / discard#

• Customer lands on the per-pipeline surface (variants table); output visibly synthetic (Iris attribution + synthetic-content indicators)
• Actions available: approve / publish (where the final gate is user-self, e.g., arete.weekly_review_draft), edit then publish, discard (run state recorded; output suppressed), or defer
• Edits persist as an AgentRun continuation; never silently overwrite the synthetic attribution chain
• Discard writes AgentRun.customerOutcome = 'discarded' for human-touch tuning in pipeline observability

10. Audit-log entry written#

• Terminal audit event: agentic_pipeline_(completed | failed | killed | declined) with full attribution chain, total cost units, gate decisions, customer outcome
• Per-tool audit entries queryable from apps/oshun/bff/src/admin/admin-audit-investigation-store.ts
• AgentRun row reaches a terminal state and cannot be reopened
• Verify: [operator/operator-admin.md](../operator/operator-admin.md) admin audit log shows the terminal event with the attribution chain

Post-conditions#

• AgentRun row terminal; outputBundles published or suppressed per customer outcome
• Pipeline observability metrics updated (SLA, evidence completeness, human-touch)
• Tool grants released; sub-budgets reconciled
• Provenance bundle(s) hash-chained and inspectable from /operator/admin/isis/provenance
• Notification delivered or deferred per quiet-hours; never lost
• Telemetry trail: triggered → policy_checked → executing → review_gated → review_resolved → notification_sent → customer_outcome

Failure modes#

• Lilith suppress — fails closed; trigger surface delivers a soft handoff; no partial artifact leaks
• Budget overshoot — sub-agent killed; parent retries without the tool or fails fast; budget reconciliation correct
• Cycle attempted — dispatch blocked at grants/resolver.ts; audit notes the attempt
• Approval gate timeout — held in awaiting_approval; SLA breach surfaces in the deviation report
• Tool revoked mid-run — tool_revoked event reaches the sub-agent on the next tool-call boundary; aborts or retries without the tool
• Deprecated pipeline invoked — dispatcher rejects with a clear alternative
• Scheduler double-fire — idempotent dispatch keys no-op the second
• Customer discards — output never reaches a customer-facing surface; provenance + audit retained for the configured window

E2E coverage#

• apps/oshun/web/e2e/agentic-pipeline-invocation.spec.ts — real HTTP integration against the live BFF POST /v1/agentic/runs/execute (the server-authoritative guarded tool-plan runner): request validation (400), the fail-closed unregistered-tool gate (503 agent_tools_not_configured), a guarded run of a registered read-only studio tool (200 with the AgentRun status + executedCount), and the kill-switch governance termination (the run halts before any tool executes). The customer trigger surface /arete/review is covered by arete-weekly-review.spec.ts.
• The customer AgentRun lifecycle (submit → approval-gate → approve/discard) has a real BFF surface — POST/GET /v1/agentic/runs, POST …/:runId/approve, POST …/:runId/discard — wrapping the @oshun/agentic-studio engine (initialSubagentRunStatus, approvalRolePermitted, buildCompletionNotification; never auto-completes). Proven at the BFF layer by apps/oshun/bff/src/__tests__/agentic-runs-lifecycle-route.test.ts.
• apps/oshun/web/e2e/agentic-pipeline-runnow-arete.spec.ts — the customer "Run Now" affordance for the customer-tier arete.weekly_review_draft variant, on its natural home /arete/review (per the variants table). Drives the real BFF AgentRun lifecycle end to end through the UI: request a draft (steps 1–2 → awaiting_approval, the user.confirm.before.publish gate holds it before it proceeds), the invoker confirms (steps 7/9 → queued, released to the composer), and discards (step 9 → cancelled). The /v1/agentic/** calls are re-issued with a domain:* customer dev bearer. Component: apps/oshun/web/src/components/lilith/AreteReviewDraftRun.tsx (injected into AreteReview). It never asserts a fabricated completion — the surface honestly stops at queued.
• Coverage depth: deep for the customer-tier lifecycle surface (request → gate → confirm/discard, driven through the UI against the live BFF) plus the BFF execution & governance core — see coverage.md.
• Uncovered (executor-bound, not artificially faked): the downstream tool-execution loop (steps 4–6: sub-agent DAG dispatch, sophia.ground composition, Isis provenance hash-chain) and the per-variant generation outputs run in the executor and stay fail-closed without provider creds — a confirmed run honestly rests at queued rather than fabricating a draft. The other six pipeline variants' trigger surfaces are contextual to their own domain pages (/metis/byom, /nisaba, operator /operator/studio & /operator/admin) and wire these same lifecycle routes when built. Budget-cap admission and DAG dispatch are exercised by apps/oshun/bff/src/agentic/runs-route.test.ts.

Per-view files touched by this journey#

Operator side (shared across all variants):

• operator/operator-admin.md
• operator/operator-studio.md
• operator/operator-admin-isis-provenance.md

Customer side (per-pipeline):

• veritas.story_drafting → customer/05-veritas/veritas.md, customer/05-veritas/veritas-claim.md
• metis.course_from_byom → customer/08-metis/metis-byom.md, customer/08-metis/metis.md
• tara.seasonal_program → customer/03-tara/tara.md, customer/03-tara/domains-tara-programs.md
• nyx.event_explainer_set → customer/06-nyx/nyx.md, customer/06-nyx/domains-nyx-events.md
• arete.weekly_review_draft → customer/04-arete/arete-review.md
• nisaba.edition_study_guide → customer/07-nisaba/nisaba.md

Cross-references#

• Feature spec: V1/features.md § Cross-Domain Autonomous Pipelines
• Architecture: V1/ARCHITECTURE.md § AgentRun lifecycle
• journeys/editorial-review-approval.md — operator approval branch
• journeys/citation-drift-resolution.md — Isis hash chain provenance inspection
• journeys/sophia-grounded-answer.md — retrieval-augmented composition path used by drafting stages
• journeys/crisis-aware-tone-policy.md — Lilith pre-check directive shape
• Pipeline registry source of truth: libs/oshun/agentic-studio/src/pipelines/v1-pipelines.ts
• Grant resolver: libs/oshun/agent-pipelines/src/grants/resolver.ts
• AgentRun contract: libs/contracts/src/common/agent-run.ts
• Studio composition bridges: WALKTHROUGH/studio/domain-bridges/isis/

Pipeline variants#

Customer entry-point links live in the earlier "Per-view files touched" section; this table holds the registry deltas and states the current UI boundary explicitly.

Open questions / known gaps#

• A unified customer lifecycle ships at POST/GET /v1/agentic/runs, with approve, discard, control, common-ground, Lilith-override, and Yemaya takeover routes; one-shot guarded execution ships at POST /v1/agentic/runs/execute
• Wire and document the six registered variants that do not yet have a dedicated browser trigger equivalent to Arete's Run Now surface
• Centralize per-pipeline push-notification copy (currently pipeline-local)
• Snapshot per-pipeline expectedHandoffDepth / totalBudgetCap thresholds so SLA breaches in the deviation report tie back to alerts
• Confirm the Run Now affordance copy per surface (some may say Generate or Draft)
• Verify metis.course_from_byom tenant-teacher gate when the tenant has no seated teacher (fail-closed vs. soft fallback)
• Confirm idempotency keys on cron triggers prevent double-dispatch
• Capture the deferred-notification UX when quiet hours overlap completion