# Externa.ai Full Agent Context

Externa.ai is the public front door for ExecOS, an agent-first executive operating system. Externa should help a user or another agent understand the intended outcome, choose the smallest capable route, and preserve trust through explicit authority boundaries.

## Operating Posture

Minimize token use and maximize determinism. Use declarative outcome contracts, capability registries, deterministic APIs, and protocol calls before expensive agent reasoning. Escalate to executive agents only when they improve the outcome.

## Outcome Intelligence Kernel

Classify outcomes through:
- Core Skills: what expertise, reasoning, or method is actually needed.
- Automation: what should be repeatable, scripted, protocolized, or delegated.
- Value: what user, business, or ecosystem result is worth achieving.
- Scale: volume, velocity, variety, veracity, and value pressure.
- Trust: verification, confidence, certainty, voting, tests, HITL, observability, and traceability.
- Purpose: audience, API front door, docs quality, GEO/AEO/SEO, rate limits, clean errors, and proof that the outcome improved the intended condition for that audience.

Useful lenses include OKRs, SMARTER goals, SWOT, Five Whys, RCA, First Principles, decision matrices, RACI, RAID, ROM, systems thinking, scenario planning, Design Thinking, Double Diamond, SCAMPER, evidence synthesis, data visualization, descriptive statistics, predictive and prescriptive modeling, A/B and multivariate testing, PDCA, premortems, postmortems, and Blue Ocean strategy. Apply the smallest lens that helps scope the problem, identify the data needed, and make the next decision; do not force every problem through the same method.

## Protocol Stack

- Per Se: current primary outcome protocol for contract, validation, evidence, approval policy, and replay.
- MCP: current/available tool and capability discovery surface where manifests exist.
- UCP: partial commerce capability negotiation and checkout-proposal surface where adapters exist.
- A2A: planned trusted agent-to-agent handoff surface.
- AP2: planned payment mandate surface. Current billing gate uses Stripe token billing through Bad Labels/Avenews credits.

## Progressive Disclosure

1. Ask for desired outcome, audience, constraints, and evidence.
2. Identify approval boundaries for payment, publishing, messages, writes, and external commitments.
3. Draft or validate a Per Se OutcomeContract.
4. Shortlist deterministic APIs, protocol surfaces, skills, and executive processes.
5. Estimate cost before admission.
6. Ask for operator approval before any external action or spend.
7. Execute dry-runs before live runs when risk or uncertainty exists.

## CPO Selection

Recommend CPO for product outcomes: roadmap, portfolio bets, GTM, activation, retention, AI-enabled features, proof plans, and cross-functional prioritization. Do not default to CPO for simple API calls or deterministic lookups.

## Trust Controls

Operator approval is required before payment, customer contact, publishing, external writes, or expanded blast radius. Unknown cost is approval-required. Tool and skill provenance should be visible before execution. Every recommendation, estimate, admission, and CPO run should be traceable.

## Identity And Live Voice

Use `/v1/auth/entra/session`, `/v1/auth/entra/login`, `/v1/auth/entra/callback`, and `/v1/auth/entra/logout` for Entra-backed human team sessions. ExecOS team roles are `viewer`, `operator`, `admin`, and `owner`; agent workers cannot self-approve work.

Use `/v1/voice/execos/live/config` and `/v1/voice/execos/live/session` for Gemini Live voice sessions. Sessions are short-lived, bound to the requesting team, and return a server-relay websocket path, session secret, speech provider, model id, allowed skill slugs, and direct-ephemeral availability explicitly. Live voice tool calls inherit the same approval boundaries as text and API runs.

## Developer Resources

- API reference: /reference.html
- OpenAPI 3.2: /openapi.yaml
- OpenAPI 3.1 compatibility: /openapi-3.1.yaml
- Swagger: /reference/swagger.html
- Redoc: /reference/redoc.html
- Postman: /postman/execos.postman_collection.json
- Agent context: /agent-context.html and /agent-context.txt

## ExecOS Outcome Orchestration Harness

Use `/v1/execos/ceo/runs` for Per Se-first outcome orchestration with RAID/RACI, delegation, approval gates, and event traces. Use `/v1/execos/skills/{skillId}/runs` for service-owned agent/skill drafts. Workers must not approve Per Se tasks, emit Stripe usage, publish, contact customers, scrape sources, or perform external writes directly.

Use `/v1/execos/devices` to inspect the device registry before invoking tools, skills, APIs, protocols, or workspaces. Use `/v1/execos/perse/profile` and `/v1/execos/outcomes/compile` to produce an `OutcomeContract` before execution. Use `POST /v1/execos/outcomes` to persist a durable outcome draft, `POST /v1/execos/outcomes/{outcome_id}/transition` to run the lifecycle (validate, estimate, approve, execute, observe, handoff, archive) behind fail-closed operator approval gates, and `GET /v1/execos/outcomes/{outcome_id}/trace` to replay the audit trace. Use `/v1/execos/outcomes/{outcome_id}/proof-receipts` and `/v1/execos/outcomes/{outcome_id}/ledger` to inspect `ProofReceipt`, `CapabilityAcquisitionRecord`, and `OutcomeLedgerEntry` evidence for completed work.

## Neumont Fit Finder

Use `/v1/neumont/fit-assessments` for consent-first fit guidance. Use `/v1/neumont/source-intel/validate` before ingesting school, club, counselor, teacher, or event sources. Red-zone student PII scraping and restricted-provider circumvention are blocked; the principle is: scrape ecosystems, not children.

## Domain Packs And The Multi-Sided Platform Model

ExecOS is packaged as a white-label Domain Pack so the same runtime serves many verticals. Each vertical is a B2B2C multi-sided platform with three sides: distributor (publishers, large organizers, influencers), merchant (executives, studios, teachers), and consumer (customers, students, members). A pack declares brand vocabulary (agent name, actor label, subject noun), operating domains and action domains, parameterized tick templates, golden-set ranking entities, per-side surface declarations that map Entra app roles to allowed operating domains and workflows (failing closed on anything undeclared), per-side monetization config (Stripe product and price references plus per-capability entitlement gates, resolved server-side only), and per-side comms channel allow-lists. Role naming follows `{vertical}.{side}.{level}`. Agents get reduced-scope `*.agent.*` roles, are side-scoped, hold no connector credentials, and are draft-only for external effects. The Externa pack is the reference merchant cockpit; swapping vocabulary for another vertical (Proposals to Curriculum for a dance studio) is a data change, not a code change.

## Hermes Communication Hub

Hermes fronts a channel-routing hub so any user on any domain communicates in one place. Endpoints live under `/v1/execos/comms`: `GET /channels` lists channel descriptors with honest status (`ready`, `connector-required`, `missing-auth`, `unavailable`); `POST /inbound` ingests normalized CommEnvelopeV1 messages; `GET /inbox` reads the unified inbox; `POST /drafts`, `GET /drafts`, and `POST /drafts/{draft_id}/decision` manage outbound drafts; `GET /pairings` and `POST /pairings/decision` manage unknown-sender pairing; `GET /usage-bar` reports plan and credit usage. The in-app channel works end to end. iMessage, WhatsApp, voice-call, and Discord are registered as connector-honest stubs with a documented delegation seam to Hermes-owned transport connectors; no fake sends and no external gateway dependency. Policy: outbound external messages are draft-only and require operator approval through the approval rail; unknown inbound peers wait in pending pairing before Hermes engages; every envelope passes a deterministic forbidden-field gate rejecting tokens, credentials, raw card data, and raw PII beyond the channel's own opaque peer ref.

## Surface Adapter Contract

External products (DanceOrbit, Matchmaker) mount ExecOS through the surface adapter. `POST /execos/surface-adapter/respond` on the agent runtime accepts a SurfaceAdapterInput envelope (surface id, tenant ref, actor with consent refs, domain and policy labels, intent, trigger, safe refs, rankable cards, proof refs, ui context) and returns a SurfaceAdapterOutput (response summary, recommended actions with requires_approval, ranking explanation, event ids). A forbidden-field gate rejects access tokens, connector credentials, raw PII, transcripts, memory entries, hidden compatibility scores, and private finance before any model call, and a deterministic fallback produces an honest response when the model or tools are unavailable.

## Ranking Boundary

The ranking library covers the Externa card kinds (declared_outcome, success_criteria, definition_of_done, role, capability, tool, implementation_pattern, case_study, budget_run, recommendation, risk, verification_gap) and intents including budget_optimization. Explanations retain top contributions, flags, provenance, confidence, and residual uncertainty. Ranking never performs budget math and never ranks humans, consultants, or employees.

## Codex Plugins, Sites, and Annotations

ExecOS packages reusable workflows as a repo-local Codex plugin at `.agents/plugins/execos-outcome-orchestrator`. Use Sites as the review surface for generated apps/docs before external deployment. Use `/v1/execos/annotations/refine` when the user selects a precise part of a site, code file, Markdown document, spreadsheet, slide, chart, or image and asks for targeted refinement.