Phase 1: Flow Walkthrough - Understanding the Protocol End-to-End

[rbadillap]

Objective

Before touching any code or structure, we need to understand the complete protocol flow. These questions challenge assumptions in the current architecture and need answers before we can categorize domains or restructure files.

Tracked in: PLAN.md (root, gitignored)

---

Questions

On the core flow

Q1: Is the Agent Loop a protocol concern or an implementation concern?

The loop (Gather → Act → Verify → Iterate) is described in concepts/agent-loop.mdx but has zero types in the schema. If the protocol does not define the loop's interface, is it actually part of the protocol, or is it guidance for implementors?

Answer:

---

Q2: What is the relationship between Workflow.run() and a Run?

Workflow<Output> has .run(prompt, options) that accepts RunOptions and returns Promise<Output>. But Run<Output> is a separate interface with .start() → Execution<Output>. Are these two entry points to the same concept? When does a caller use one vs the other?

Answer:

---

Q3: Where does initial routing happen?

When a task arrives, something must decide which agent handles it. The Lifecycle says "Discovery" does this. But there are no types for Discovery. RoutingWorkflow is a workflow pattern, not a system-level router. Who or what performs the initial routing?

Answer:

---

On domain boundaries

Q4: Are the 7 protocol domains the right taxonomy?

ProtocolDomain defines: system, context, actions, checks, skills, workflows, runs. But:

• skills (orchestrator, planner, executor) looks more like agent archetypes than a "domain"
• actions (tools, ops, mcp-servers) overlaps with what MCP already standardizes

Are all 7 earning their place, or should some be collapsed/removed?

Answer:

---

Q5: What is the boundary between system and context?

System has: registry, env, fs, settings, data. Context has: memory, documents, embeddings, apps, system-context. Memory and Storage seem related. Where exactly is the line between "the OS provides state infrastructure" and "agents manage their own context"?

Answer:

---

Q6: Should checks be a domain or part of the Agent Loop Verify step?

The taxonomy puts quality checks as their own domain AND as "Quality Workflows" AND as step 3 of the Agent Loop. The same concern described three different ways. Which is it?

Answer:

---

On the ecosystem

Q7: What does Syner SDK actually implement from this protocol?

Which types are exercised by working code in the SDK? This tells us which interfaces are validated by real usage vs purely theoretical.

Answer:

---

Q8: How does OSP integrate with MCP concretely?

actions/mcp-servers.ts and system/mcp-client.ts are empty. Is OSP a consumer of MCP servers? A coordinator? A wrapper? What is the actual integration surface?

Answer:

---

On the OS metaphor

Q9: Is the OS metaphor structural or pedagogical?

Does the OS metaphor drive architectural decisions (e.g., "we need system/fs.ts because OSes have filesystems"), or is it a teaching tool? The answer determines whether empty system files should exist.

Answer:

---

Q10: Who is the consumer of this protocol?

Framework authors? Individual developers? Platform operators? The answer determines the level of abstraction the schema should provide.

Answer:

---

Process

1. Ronny answers the questions above (directly in this issue or in conversation)
2. Answers get summarized and promoted to PLAN.md Decisions Log
3. Issue gets closed when all 10 questions have clear answers
4. Phase 2 (Domain Categorization) begins

[rbadillap]

Q1 Answer: Agent Loop is Protocol Concern — Enforced via Domain Types (Vertiente B)

Summary

The Agent Loop (Gather → Act → Verify → Iterate) is a protocol concern, not optional guidance. Every agent that creates a Run MUST follow the loop. However, the loop is enforced implicitly through domain types, not through a single AgentLoop interface.

How it works

Each phase of the loop maps to a protocol domain:

• Gather → context/ types (memory, documents, embeddings)
• Act → actions/ types (tools, ops) + workflows/
• Verify → checks/ types (rules, judge, audit)
• Iterate → runs/ types (RunStatus, Execution lifecycle)

Agents compose these domains as needed. A run might need judge in one scenario and skip it in another — the protocol enables both paths without forcing a rigid interface.

Key clarifications from Ronny

• Planning is a workflow, not a loop phase. Any planning agent still follows the same loop (gather info → act → present result). Planning workflows are "hackable" — Syner (first implementor) will create its own, including a planning workflow.
• System APIs are implementation concern. Any vendor can integrate their services into the OS, but the loop itself is protocol-level.
• Adopted from Anthropic (Claude Agent SDK blog post), not an original concept.

Why not a unified AgentLoop interface?

• The implicit approach is more flexible for agents (they choose which domains to compose)
• Better for agentic adoption — agents can pick the best path per run
• Reinforces the need for strong documentation (which the protocol already prioritizes)
• Easier agent creation at the code level
• No breaking changes when domains evolve independently

Decision

Vertiente B selected. The Agent Loop is enforced through documentation and domain type composition, not through a monolithic interface.

---

Q2 Answer: Workflow Defines Pattern, Run Executes — Separation of Concerns

Summary

Workflow and Run are complementary concepts with clear separation:

• Workflow (inspired by Anthropic's building blocks) = the execution pattern. Defines HOW work is structured.
• Run (inspired by ACP) = the execution itself. Has lifecycle, status, and control APIs.

A Run always has a Workflow. No Run without Workflow.

Design decision

Workflow.run() is removed. The API becomes explicit:

// Workflow defines the PATTERN
interface Workflow<Output> {
  type: string
  prepare(prompt: string): Promise<WorkflowPlan>
}

// Run executes WITH a workflow
interface Run<Output> {
  id: string
  status: RunStatus
  workflow: Workflow<Output>
  options: RunOptions<Output>
  start(): Promise<Execution<Output>>
}

// Flow: orchestrator picks workflow → creates run → starts execution
const workflow = selectWorkflow(intent)
const run = createRun({ workflow, options: { timeout, retry } })
const execution = await run.start()
await execution.waitForApproval("Review this?")  // human-in-the-loop
const result = await execution.result

Key clarifications from Ronny

• The protocol is agent-first, not agent-only. Humans participate specifically within Runs via the approval/waitForApproval API (human-in-the-loop). Any run can be paused for human intervention and then resumed. Outside of that, everything is agentic.
• Workflows are protocol concern but extensible — they can be replaced, refactored, or extended by users/implementors.
• The orchestrator agent identifies intent → selects workflow → executes run. This is the agentic flow.

Rationale

• Clear separation: Workflow = what pattern, Run = execution with lifecycle
• Workflow.run() was a convenience shorthand hiding the Run — better to be explicit
• Human-in-the-loop lives in Execution, not in Workflow
• The orchestrator agent works with Runs, not by invoking workflows directly

[rbadillap]

Q3 Answer: Initial routing is the orchestrator agent's job

Summary

The orchestrator agent (in Syner OS = packages/syner) performs initial routing. There is no separate "Discovery" system component.

The mechanism already exists in the schema:

• AgentAnnotations.whenToUse + examples → the orchestrator uses these to match intent to agent
• AgentRegistryEntry → the orchestrator queries the registry to know what agents exist

No new types needed. Discovery is a capability of the orchestrator, not a standalone system service.

---

Q4 Answer: 7 domains → 4 categories. Skills removed from protocol.

Summary

The 7 flat protocol domains (system, context, actions, checks, skills, workflows, runs) are restructured into 4 categories:

Category	Domains	Purpose
Agent Loop	context, actions, checks	The 3 phases of the loop (gather, act, verify). Protocol defines types, vendors implement APIs.
System (OS)	system	Infrastructure APIs for vendors integrating into the agent loop (e.g., Vercel Sandbox, storage providers).
Execution	workflows, runs	Complementary pair: workflows define patterns, runs execute them. The infrastructure-level loop.
Skills	removed	Orchestrator/planner/executor are implementation concern, not protocol.

Why remove Skills from the protocol?

The roles (orchestrator, planner, executor) are emergent behaviors from workflows, not formal contracts:

• An agent running a RoutingWorkflow behaves as an orchestrator
• An agent running an OrchestratorWorkersWorkflow behaves as a planner + coordinator
• An agent receiving a delegated PlanStep behaves as an executor

The same agent can be orchestrator in one run and executor in another. The workflow already defines the behavior — separate role interfaces would be redundant.

Syner OS (the reference implementation) will provide pre-configured agents optimized for these roles, but that is implementation concern, not protocol specification.

Key clarification from Ronny

"System APIs are for vendors that want to integrate into the agent loop with their services or infrastructure. Context, actions, and checks are the agent loop phases. Workflows and runs share a category — execution at the infrastructure level. Skills were created as a reminder that orchestrator/planner/executor are agents with specific functionality, but I agree they don't belong in the protocol."

Impact

• ProtocolDomain type will be updated to remove skills
• packages/schema/skills/ directory will be removed
• Documentation pages for skills/orchestrator, skills/planner, skills/executor will be removed
• The concept moves to Syner OS scope

[rbadillap]

Q5 Answer: System = platform environment, Context = agent-consumed information

Summary

The boundary is a layered relationship:

• System = the environment where the agent runs. Platform infrastructure, vendor-provided APIs (storage, cache, registry, env, fs). Static relative to the agent — it consumes but does not define it.
• Context = the information provided to the agent for decision-making. Dynamic — changes per run, per task, per loop phase. Agent-consumed APIs (memory, documents, embeddings).

Context is built on top of System but exposes an agent-oriented interface. For example, context/memory might use system/data/storage underneath, but the contract is different.

Key clarification from Ronny

"The system is the environment in which the agent runs, while the context is the information provided to the agent so it can make decisions and take actions. During the context (gather) phase, an agent can read from the system but not modify it. During the actions phase, it can modify documents — it all depends on the plan."

Implication

• system/ = vendor-provided platform APIs
• context/ = agent-consumed information APIs (may use system under the hood)
• The relationship is layered, not flat

---

Q6 Answer: Checks = Verification phase of the Agent Loop

Summary

checks is simply the short name for the verification phase of the Agent Loop: context → actions → verification (checks).

It is not a separate domain — it is the third phase of the loop. The three descriptions (domain, quality workflows, loop phase) are three perspectives of the same concept. The domain (checks/) is the source of truth for the types.

Key clarification from Ronny

"I used the word checks to keep it short, but if you look at the agent loop, it starts with context → action → verification (this is checks and all the APIs this namespace offers). The checks are a fundamental part of the agent lifecycle — they verify integrity and quality of data and results during execution. All the APIs in this phase serve one purpose: present results and wait for approval from a supervising agent or a human."

Important connection

The verification phase connects to human-in-the-loop: verification not only validates results but also presents results and awaits approval (from a supervisor agent or human). This links checks/ to runs/approval — verification can trigger an approval request within the Execution lifecycle.

Naming convention

Under discussion: whether to rename checks/ → verification/ to align with the Agent Loop phase name, or keep checks/ for brevity with documentation always referencing "Verification (checks)". Decision deferred to Phase 5 (Structure Review).

[rbadillap]

Q5 Addendum: context/system.ts validates the layered relationship

After further discussion, we identified that context/system.ts (currently empty) was intentionally placed as the agent-oriented interface to system information during the gather phase.

This validates the Q5 decision: context is built on top of system. context/system.ts is the "lens" through which an agent sees the system during the context phase — same pattern as the entire Agent Loop, where interfaces direct everything and implementations vary.

No tension. No additional tasks beyond what was already captured.

[rbadillap]

Q7 Answer: Syner SDK partially implements the protocol

Summary

Syner SDK is under active development and does not yet cover 100% of the protocol. Validated integrations:

• Upstash → maps to system/data (Cache/Storage) and context/memory
• Vercel Sandbox → maps to system/ (execution environment)

The remaining types (workflows, runs) are conceptually correct but not yet exercised by real implementations. The documentation is already adopting the pattern of including real-world use cases based on these integrations, and the plan is to continue that approach.

Implication for Phase 3

When we reach Interface Analysis, we should cross-reference the Syner SDK to validate that schema types align with what the implementation actually needed. Types validated by real code (Cache, Storage, memory) have higher confidence than purely theoretical ones.

---

Q8 Answer: MCP has two distinct roles in OSP

Summary

MCP integration is split into two separate concerns:

Role	Location	Purpose
MCP Client	system/mcp-client.ts	Infrastructure concern. Allows the OS to support external MCP servers of various types. Vendor-provided capability.
MCP Server	actions/mcp-servers.ts	Agent communication channel. Exposes information through the protocol so other agents can interact via MCP. Agent-to-agent communication.

Key clarification from Ronny

"MCP as client is for operating systems like Syner OS to offer the capability of supporting different types of MCPs. As server, the idea is that through an MCP server we can establish communication with an agent through the protocol to obtain information. Remember that OSP is oriented agent → agent, so MCP is a great example of communication we can establish."

[rbadillap]

Q9 Answer: The OS metaphor is structural, not pedagogical

Summary

The OS metaphor dictates the architecture. It is the framework for deciding where any concept belongs in the protocol:

OS Concept	OSP Mapping	Decision Rule
Kernel / Drivers	system/	Infrastructure for vendors → goes in system
User Space / Syscalls	context/	Information consumed by agents → goes in context
Scheduler	workflows/ + runs/	Execution patterns and lifecycle → goes in execution
Process Cycle	Agent Loop	The cognitive micro-cycle every agent follows

Evidence from our Q&A:

• Q4: System is explicitly "APIs for vendors integrating infrastructure" — like device drivers
• Q5: Context is built on system but exposes agent-oriented interfaces — like syscalls
• Q5 addendum: context/system.ts is the agent's lens to the system — literally a syscall interface
• Q8: MCP Client lives in system as infrastructure — like a communication driver

The metaphor is not just for explaining. It is the decision framework for the entire protocol structure.

---

Q10 Answer: Framework authors and platform builders

Summary

Primary consumers: Authors of frameworks/platforms that build multi-agent systems (e.g., Syner OS).

Secondary consumers: Vendors integrating their services into the agent ecosystem (e.g., Upstash for cache/memory, Vercel for sandbox execution).

The individual developer consumes the implementation (Syner OS or any conformant platform), not the protocol directly. The protocol defines interoperability contracts between multi-agent systems.

The human acquires the role of supervisor — participating specifically through human-in-the-loop within Runs (approval/waitForApproval), while everything else operates agentically.

---

Phase 1 Complete

All 10 questions have been answered. Key decisions:

1. Agent Loop = protocol concern, enforced via domain types (no monolithic interface)
2. Workflow/Run separation = Workflow defines pattern, Run executes. Workflow.run() removed.
3. Routing = orchestrator agent's responsibility, no Discovery type needed
4. 4 categories replace 7 flat domains: Agent Loop (context, actions, checks), System, Execution (workflows, runs). Skills removed.
5. System vs Context = layered. System = vendor-provided platform. Context = agent-consumed, built on system.
6. Checks = verification phase of Agent Loop, naming decision deferred
7. Syner SDK = partial implementation (Upstash, Vercel). Real use cases driving docs.
8. MCP = two roles: Client in system/ (infrastructure), Server in actions/ (agent communication)
9. OS metaphor = structural, dictates architecture decisions
10. Consumers = framework/platform authors primarily, vendors secondarily. Humans = supervisors.

Moving to Phase 2: Domain Categorization.

[rbadillap]

Reopening for future reference

[rbadillap]

Documented, also created a skill for this.