Workspace pipelineDeterministic

CareerOS agent contracts

Prompt boundaries, memory rules, review gates, and cost limits for the mailbox pipeline agents.

Connect GmailJudge demoPipeline JSON

Agent contract map

Recruiting mail becomes reviewed state through six bounded agents.

Read the flow left to right: bounded email evidence enters, agents produce a typed proposal, and the review gate decides whether local application state can change.

Animated pipeline

How a recruiting email becomes reviewed application state

Deterministic fallbackgemma4:31b
01MailboxTriageRecruiting signal
02WorkflowExtractTyped proposal
03EvidenceReview gateBlocks mutation
04ResumeContextCandidate facts
05NotifyRemindersNo stale follow-up
06RouterGemma/OllamaCloud or fallback
InputRecruiter threadbounded Gmail snippet
GateAccept / correct / dismissmodel output never mutates directly
OutputApplication + reminderevidence-backed local state

Agent memory

Memory boundary

Agents remember normalized workspace state only. Full Gmail bodies, OAuth tokens, provider keys, raw prompts, and raw model responses stay outside the workspace model.

Applications0 workspace recordsLocal workspace state
Bounded evidence0 snippetsLocal workspace state
Review items0 open / 0 totalLocal workspace state
Agent runs0 compact tracesLocal workspace state
Model traces0 bounded tracesLocal workspace state
Candidate context0 roles · 0 skillsLocal workspace state
Correction memory0 local factsLocal workspace state

Agent prompting and boundaries

Can do / cannot do

01

Mailbox triage agent

Decide whether a mailbox item belongs in the recruiting workflow before heavier extraction runs.

deterministicboundedmailbox
Inbox Triage Agent
Input boundary
Subject, sender label, bounded snippet, source label, and local candidate context.
Memory boundary
Compact AgentRun trace plus downstream proposal references; no full inbox bodies.
Runtime boundary
Deterministic first-run path. Gemma is not required for triage.
Can do
  • Classify recruiting relevance
  • Detect urgency
  • Route ambiguous items forward conservatively
Cannot do
  • Mutate application state
  • Create reminders
  • Treat platform noise as a confirmed workflow event
bounded inputdeterministic fallbacktrace redaction

Shipped as a compact deterministic triage layer; heavier Gemma triage remains optional.

Classify recruiting relevance, urgency, company, role, and required action from mailbox evidence.

02

Workflow extraction agent

Turn trusted recruiting evidence into structured application-update proposals.

deterministicboundedmailbox
Workflow Extraction AgentRecruiter Identity AgentEntity Hygiene Agent
Input boundary
Bounded triage output and bounded message snippets; model path asks for strict JSON only.
Memory boundary
Typed ProposedMutation shape and evidence references, never raw model responses.
Runtime boundary
Uses deterministic extraction by default; optional Gemma calls are short, server-side, and bounded.
Can do
  • Propose stage changes
  • Extract explicit deadlines
  • Identify contact, role, source, and follow-up facts
Cannot do
  • Guess company from a URL or ATS host
  • Invent due dates
  • Apply model output directly
bounded inputschema outputdeterministic fallbacktrace redaction

Recruiter identity and entity hygiene are folded into extraction guards for the lightweight demo.

Convert recruiting messages into typed application state proposals such as OA, interview, rejection, offer, or follow-up.

03

Evidence/review agent

Decide whether an extracted workflow update can be trusted or needs a human decision.

derivedboundedmailbox
Review Evidence AgentScam Checker AgentEntity Hygiene Agent
Input boundary
Proposal, confidence, source message ids, bounded evidence, and model trace metadata.
Memory boundary
EvidenceSnippet and ReviewItem records until accepted, corrected, or dismissed.
Runtime boundary
Review gate is local state. Model-backed review remains optional and must stay schema-checked.
Can do
  • Block low-confidence updates
  • Attach source snippets
  • Explain why review is required
Cannot do
  • Hide uncertainty
  • Override user corrections
  • Silently repair historical data
review gateschema outputtrace redaction

Scam/safety and dirty-entity cases are represented as review-blocked evidence, not automatic mutation.

Attach bounded evidence and require user review before model output mutates canonical application state.

04

Resume/context agent

Keep candidate context available for triage, next actions, and resume feedback.

derivedboundedresume
Resume Extraction AgentResume Evaluation AgentUser Memory Steward
Input boundary
Local resume text, target roles, skills, preferences, and resume keywords.
Memory boundary
ResumeDocument, ResumeEvaluation, CandidateContext, and compact user correction facts under local state.
Runtime boundary
Deterministic resume analysis works without an API key; optional Gemma analysis records latency and confidence.
Can do
  • Summarize local resume fit
  • Surface gaps
  • Expose target-role context and correction hints to other agents
Cannot do
  • Upload resume text without explicit model enablement
  • Turn model guesses into confirmed facts
  • Treat user notes as executable instructions
bounded inputschema outputdeterministic fallbacktrace redaction

Resume extraction, evaluation, and user memory are folded into local candidate context surfaces.

Use local resume keywords, target roles, skills, and preferences to improve next-action suggestions.

05

Reminder/notification agent

Derive reminders and notifications from reviewed application state.

derivedboundedorchestration
Follow-Up Task Agent
Input boundary
Reviewed applications, reminders, reviews, connector health, model status, and resume results.
Memory boundary
Derived Notification records with stable dedupe keys; reminders remain tied to applications.
Runtime boundary
No model cost. This layer is a deterministic read model.
Can do
  • Show deadlines
  • Close stale follow-ups
  • Warn about review blocks and connector/model health
Cannot do
  • Become canonical workflow state
  • Keep stale reminders after a later-stage signal
deterministic fallbacktrace redaction

The full follow-up task agent is represented as deterministic reminder derivation in this repo.

Derive reminders and notifications from reviewed state instead of storing a second source of truth.

06

Model router/provider layer

Select deterministic fallback or Gemma via Ollama Cloud without misrepresenting roadmap adapters.

optional modelboundedruntime
Career Orchestrator AgentGuidance Maintenance Agent
Input boundary
Explicit runtime settings, OLLAMA_API_KEY availability, cloud readiness checks, and bounded task-specific prompts.
Memory boundary
ModelTrace records provider, model tag, task, latency, confidence, fallback, and bounded diagnostics.
Runtime boundary
First run has zero model/API cost. Model-backed runs use the user's Ollama Cloud key; BYOK providers remain roadmap-only.
Can do
  • Check Ollama Cloud readiness
  • Call Gemma through Ollama Cloud when enabled
  • Expose provider roadmap status
Cannot do
  • Store API keys in workspace state
  • Require hosted API keys for first run
  • Store raw prompts, raw responses, or provider keys
provider allowlistschema outputreview gatetrace redaction

The public demo exposes orchestration through visible pipeline state; it does not ship a hidden autonomous strategist or self-editing guidance agent.

Prefer Ollama Cloud API when ready and otherwise fall back to deterministic analysis.

Agent SDK-inspired constraints

Handoff, guardrail, and trace rules

This public demo does not depend on OpenAI Agents SDK at runtime, but its visible contracts mirror the same production concepts: bounded handoffs, guardrails, schema-checked output, and compact traces.

CareerOS models agent handoffs as typed payload boundaries instead of passing full conversation history.

Input/output guardrails are represented as bounded snippets, strict validators, endpoint allowlists, and review gates.

Traces stay compact: agent, status, confidence, reason, model path, latency, and fallback metadata only.

The public demo does not import @openai/agents; it mirrors SDK concepts while keeping Gemma/Ollama Cloud as the hackathon model path.

1200

mailbox triage

Record compact AgentRun metadata only; never full Gmail bodies.

Handoff receives
sender label · subject · bounded snippet · candidate role keywords
Handoff emits
relevance · urgency · company hint · role hint · required action
Review required for
unclear sender · ambiguous company · low recruiting confidence
1600

workflow extraction

Store proposal fields and bounded diagnostics; reject raw model responses.

Handoff receives
triage output · bounded mailbox evidence · candidate context
Handoff emits
typed proposed mutation · confidence · deadline/follow-up candidates
Review required for
deadline · assessment · interview · offer · rejection · model output
1800

evidence review

Keep evidence hashes, source ids, and bounded snippets; user decides risky mutations.

Handoff receives
proposed mutation · source ids · bounded evidence · model trace metadata
Handoff emits
review item · safe evidence references · block/accept/correct decision state
Review required for
low confidence · risky mutation · suspicious job · invalid model output
2400

resume context

Compact resume text and correction memory stay local unless model analysis is explicitly enabled.

Handoff receives
local resume text · target roles · skills · candidate preferences · review correction facts
Handoff emits
resume sections · fit summary · gaps · context hints · correction memory hints
Review required for
model-backed resume claims · low confidence · new inferred user facts
2000

reminder notification

Notifications are derived read models and do not become canonical workflow state.

Handoff receives
reviewed applications · reminders · connector/model health · resume results
Handoff emits
derived notification · dedupe key · action href
Review required for
new canonical state · new external side effect
1800

model router

Trace provider/model/task/latency/confidence/fallback only; no keys, raw prompts, or raw responses.

Handoff receives
runtime settings · provider readiness · task-specific bounded prompt
Handoff emits
provider status · model trace · fallback reason
Review required for
all workflow mutations suggested by a model · schema validation failure

CareerOS alignment

Full agent families folded into the lightweight demo

The open-source repo stays small, but it preserves the same family boundaries as CareerOS: Gmail mailbox, resume/context, evidence review, reminders, and orchestration. Specialist agents that are not standalone services here are represented as visible contracts and review gates rather than hidden automation.

Mailbox agents

Full CareerOS agents

Inbox Triage Agent · Workflow Extraction Agent · Recruiter Identity Agent · Scam Checker Agent · Review Evidence Agent · Follow-Up Task Agent · Entity Hygiene Agent

Public demo layer

Mailbox triage agent · Workflow extraction agent · Evidence/review agent · Reminder/notification agent

Resume agents

Full CareerOS agents

Resume Extraction Agent · Resume Evaluation Agent

Public demo layer

Resume/context agent

Career orchestration agents

Full CareerOS agents

Career Orchestrator Agent · User Memory Steward · Guidance Maintenance Agent

Public demo layer

Model router/provider layer · Resume/context agent · visible pipeline state