agent/docs/RFC-GO-AGENT-MODELS.md

# core-agent — Models

> Structs, interfaces, and types extracted from source by Codex.
> Packages: agentic, brain, lib, messages, monitor, setup.

## agentic

**Import:** `dappco.re/go/agent/pkg/agentic`
**Files:** 27

Package agentic provides MCP tools for agent orchestration.
Prepares workspaces and dispatches subagents.

## Types

### AgentsConfig
- **File:** queue.go
- **Purpose:** AgentsConfig is the root of config/agent.yaml.
- **Fields:**
  - `Version int` — Configuration version number.
  - `Dispatch DispatchConfig` — Dispatch-specific configuration.
  - `Concurrency map[string]ConcurrencyLimit` — Per-pool concurrency settings.
  - `Rates map[string]RateConfig` — Per-pool rate-limit configuration.

### BlockedInfo
- **File:** status.go
- **Purpose:** BlockedInfo shows a workspace that needs human input.
- **Fields:**
  - `Name string` — Name of the item.
  - `Repo string` — Repository name.
  - `Agent string` — Agent name or pool identifier.
  - `Question string` — Blocking question that needs an answer.

### ChildRef
- **File:** epic.go
- **Purpose:** ChildRef references a child issue.
- **Fields:**
  - `Number int` — Numeric identifier.
  - `Title string` — Title text.
  - `URL string` — URL for the item.

### CompletionEvent
- **File:** events.go
- **Purpose:** CompletionEvent is emitted when a dispatched agent finishes. Written to ~/.core/workspace/events.jsonl as append-only log.
- **Fields:**
  - `Type string` — Type discriminator.
  - `Agent string` — Agent name or pool identifier.
  - `Workspace string` — Workspace identifier or path.
  - `Status string` — Current status string.
  - `Timestamp string` — Timestamp recorded for the event.

### ConcurrencyLimit
- **File:** queue.go
- **Purpose:** ConcurrencyLimit supports both flat (int) and nested (map with total + per-model) formats.
- **Fields:**
  - `Total int` — Total concurrent dispatches allowed for the pool.
  - `Models map[string]int` — Per-model concurrency caps.

### CreatePRInput
- **File:** pr.go
- **Purpose:** CreatePRInput is the input for agentic_create_pr.
- **Fields:**
  - `Workspace string` — workspace name (e.g. "mcp-1773581873")
  - `Title string` — PR title (default: task description)
  - `Body string` — PR body (default: auto-generated)
  - `Base string` — base branch (default: "main")
  - `DryRun bool` — preview without creating

### CreatePROutput
- **File:** pr.go
- **Purpose:** CreatePROutput is the output for agentic_create_pr.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `PRURL string` — Pull request URL.
  - `PRNum int` — Pull request number.
  - `Title string` — Title text.
  - `Branch string` — Branch name.
  - `Repo string` — Repository name.
  - `Pushed bool` — Whether changes were pushed upstream.

### DispatchConfig
- **File:** queue.go
- **Purpose:** DispatchConfig controls agent dispatch behaviour.
- **Fields:**
  - `DefaultAgent string` — Default agent used when one is not supplied.
  - `DefaultTemplate string` — Default prompt template slug.
  - `WorkspaceRoot string` — Root directory used for prepared workspaces.

### DispatchInput
- **File:** dispatch.go
- **Purpose:** DispatchInput is the input for agentic_dispatch.
- **Fields:**
  - `Repo string` — Target repo (e.g. "go-io")
  - `Org string` — Forge org (default "core")
  - `Task string` — What the agent should do
  - `Agent string` — "codex" (default), "claude", "gemini"
  - `Template string` — "conventions", "security", "coding" (default)
  - `PlanTemplate string` — Plan template slug
  - `Variables map[string]string` — Template variable substitution
  - `Persona string` — Persona slug
  - `Issue int` — Forge issue number → workspace: task-{num}/
  - `PR int` — PR number → workspace: pr-{num}/
  - `Branch string` — Branch → workspace: {branch}/
  - `Tag string` — Tag → workspace: {tag}/ (immutable)
  - `DryRun bool` — Preview without executing

### DispatchOutput
- **File:** dispatch.go
- **Purpose:** DispatchOutput is the output for agentic_dispatch.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Agent string` — Agent name or pool identifier.
  - `Repo string` — Repository name.
  - `WorkspaceDir string` — Workspace directory path.
  - `Prompt string` — Rendered prompt content.
  - `PID int` — Process ID for the spawned agent.
  - `OutputFile string` — Path to the captured process output file.

### DispatchSyncInput
- **File:** dispatch_sync.go
- **Purpose:** DispatchSyncInput is the input for a synchronous (blocking) task run.
- **Fields:**
  - `Org string` — Forge organisation or namespace.
  - `Repo string` — Repository name.
  - `Agent string` — Agent name or pool identifier.
  - `Task string` — Task description.
  - `Issue int` — Issue number.

### DispatchSyncResult
- **File:** dispatch_sync.go
- **Purpose:** DispatchSyncResult is the output of a synchronous task run.
- **Fields:**
  - `OK bool` — Whether the synchronous dispatch finished successfully.
  - `Status string` — Current status string.
  - `Error string` — Error message, if the operation failed.
  - `PRURL string` — Pull request URL.

### EpicInput
- **File:** epic.go
- **Purpose:** EpicInput is the input for agentic_create_epic.
- **Fields:**
  - `Repo string` — Target repo (e.g. "go-scm")
  - `Org string` — Forge org (default "core")
  - `Title string` — Epic title
  - `Body string` — Epic description (above checklist)
  - `Tasks []string` — Sub-task titles (become child issues)
  - `Labels []string` — Labels for epic + children (e.g. ["agentic"])
  - `Dispatch bool` — Auto-dispatch agents to each child
  - `Agent string` — Agent type for dispatch (default "claude")
  - `Template string` — Prompt template for dispatch (default "coding")

### EpicOutput
- **File:** epic.go
- **Purpose:** EpicOutput is the output for agentic_create_epic.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `EpicNumber int` — Epic issue number.
  - `EpicURL string` — Epic issue URL.
  - `Children []ChildRef` — Child issues created under the epic.
  - `Dispatched int` — Number of child issues dispatched to agents.

### ListPRsInput
- **File:** pr.go
- **Purpose:** ListPRsInput is the input for agentic_list_prs.
- **Fields:**
  - `Org string` — forge org (default "core")
  - `Repo string` — specific repo, or empty for all
  - `State string` — "open" (default), "closed", "all"
  - `Limit int` — max results (default 20)

### ListPRsOutput
- **File:** pr.go
- **Purpose:** ListPRsOutput is the output for agentic_list_prs.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Count int` — Number of pull requests returned.
  - `PRs []PRInfo` — Pull requests returned by the query.

### MirrorInput
- **File:** mirror.go
- **Purpose:** MirrorInput is the input for agentic_mirror.
- **Fields:**
  - `Repo string` — Specific repo, or empty for all
  - `DryRun bool` — Preview without pushing
  - `MaxFiles int` — Max files per PR (default 50, CodeRabbit limit)

### MirrorOutput
- **File:** mirror.go
- **Purpose:** MirrorOutput is the output for agentic_mirror.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Synced []MirrorSync` — Repositories that were synchronised.
  - `Skipped []string` — Skipped items or skip reason, depending on context.
  - `Count int` — Number of repos included in the mirror result.

### MirrorSync
- **File:** mirror.go
- **Purpose:** MirrorSync records one repo sync.
- **Fields:**
  - `Repo string` — Repository name.
  - `CommitsAhead int` — Number of commits ahead of the mirror target.
  - `FilesChanged int` — Number of changed files included in the sync.
  - `PRURL string` — Pull request URL.
  - `Pushed bool` — Whether changes were pushed upstream.
  - `Skipped string` — Skipped items or skip reason, depending on context.

### PRInfo
- **File:** pr.go
- **Purpose:** PRInfo represents a pull request.
- **Fields:**
  - `Repo string` — Repository name.
  - `Number int` — Numeric identifier.
  - `Title string` — Title text.
  - `State string` — Current state value.
  - `Author string` — Pull request author name.
  - `Branch string` — Branch name.
  - `Base string` — Base branch for the pull request.
  - `Labels []string` — Label names applied to the issue or pull request.
  - `Mergeable bool` — Whether Forge reports the PR as mergeable.
  - `URL string` — URL for the item.

### Phase
- **File:** plan.go
- **Purpose:** Phase represents a phase within an implementation plan.
- **Fields:**
  - `Number int` — Numeric identifier.
  - `Name string` — Name of the item.
  - `Status string` — pending, in_progress, done
  - `Criteria []string` — Acceptance criteria for the phase.
  - `Tests int` — Expected test count for the phase.
  - `Notes string` — Free-form notes attached to the object.

### Plan
- **File:** plan.go
- **Purpose:** Plan represents an implementation plan for agent work.
- **Fields:**
  - `ID string` — Stable identifier.
  - `Title string` — Title text.
  - `Status string` — draft, ready, in_progress, needs_verification, verified, approved
  - `Repo string` — Repository name.
  - `Org string` — Forge organisation or namespace.
  - `Objective string` — Plan objective.
  - `Phases []Phase` — Plan phases.
  - `Notes string` — Free-form notes attached to the object.
  - `Agent string` — Agent name or pool identifier.
  - `CreatedAt time.Time` — Creation timestamp.
  - `UpdatedAt time.Time` — Last-update timestamp.

### PlanCreateInput
- **File:** plan.go
- **Purpose:** PlanCreateInput is the input for agentic_plan_create.
- **Fields:**
  - `Title string` — Title text.
  - `Objective string` — Plan objective.
  - `Repo string` — Repository name.
  - `Org string` — Forge organisation or namespace.
  - `Phases []Phase` — Plan phases.
  - `Notes string` — Free-form notes attached to the object.

### PlanCreateOutput
- **File:** plan.go
- **Purpose:** PlanCreateOutput is the output for agentic_plan_create.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `ID string` — Stable identifier.
  - `Path string` — Filesystem path for the generated or stored item.

### PlanDeleteInput
- **File:** plan.go
- **Purpose:** PlanDeleteInput is the input for agentic_plan_delete.
- **Fields:**
  - `ID string` — Stable identifier.

### PlanDeleteOutput
- **File:** plan.go
- **Purpose:** PlanDeleteOutput is the output for agentic_plan_delete.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Deleted string` — Identifier of the deleted plan.

### PlanListInput
- **File:** plan.go
- **Purpose:** PlanListInput is the input for agentic_plan_list.
- **Fields:**
  - `Status string` — Current status string.
  - `Repo string` — Repository name.

### PlanListOutput
- **File:** plan.go
- **Purpose:** PlanListOutput is the output for agentic_plan_list.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Count int` — Number of plans returned.
  - `Plans []Plan` — Plans returned by the query.

### PlanReadInput
- **File:** plan.go
- **Purpose:** PlanReadInput is the input for agentic_plan_read.
- **Fields:**
  - `ID string` — Stable identifier.

### PlanReadOutput
- **File:** plan.go
- **Purpose:** PlanReadOutput is the output for agentic_plan_read.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Plan Plan` — Returned plan data.

### PlanUpdateInput
- **File:** plan.go
- **Purpose:** PlanUpdateInput is the input for agentic_plan_update.
- **Fields:**
  - `ID string` — Stable identifier.
  - `Status string` — Current status string.
  - `Title string` — Title text.
  - `Objective string` — Plan objective.
  - `Phases []Phase` — Plan phases.
  - `Notes string` — Free-form notes attached to the object.
  - `Agent string` — Agent name or pool identifier.

### PlanUpdateOutput
- **File:** plan.go
- **Purpose:** PlanUpdateOutput is the output for agentic_plan_update.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Plan Plan` — Returned plan data.

### PrepInput
- **File:** prep.go
- **Purpose:** PrepInput is the input for agentic_prep_workspace. One of Issue, PR, Branch, or Tag is required.
- **Fields:**
  - `Repo string` — required: e.g. "go-io"
  - `Org string` — default "core"
  - `Task string` — task description
  - `Agent string` — agent type
  - `Issue int` — Forge issue → workspace: task-{num}/
  - `PR int` — PR number → workspace: pr-{num}/
  - `Branch string` — branch → workspace: {branch}/
  - `Tag string` — tag → workspace: {tag}/ (immutable)
  - `Template string` — prompt template slug
  - `PlanTemplate string` — plan template slug
  - `Variables map[string]string` — template variable substitution
  - `Persona string` — persona slug
  - `DryRun bool` — preview without executing

### PrepOutput
- **File:** prep.go
- **Purpose:** PrepOutput is the output for agentic_prep_workspace.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `WorkspaceDir string` — Workspace directory path.
  - `RepoDir string` — Local repository checkout directory.
  - `Branch string` — Branch name.
  - `Prompt string` — Rendered prompt content.
  - `Memories int` — Number of recalled memories injected into the prompt.
  - `Consumers int` — Number of dependent modules or consumers discovered.
  - `Resumed bool` — Whether the workspace was resumed instead of freshly prepared.

### PrepSubsystem
- **File:** prep.go
- **Purpose:** PrepSubsystem provides agentic MCP tools for workspace orchestration. Agent lifecycle events are broadcast via c.ACTION(messages.AgentCompleted{}).
- **Fields:**
  - `core *core.Core` — Core framework instance for IPC, Config, Lock
  - `forge *forge.Forge` — Forge client used for issue, PR, and repository operations.
  - `forgeURL string` — Forge base URL.
  - `forgeToken string` — Forge API token.
  - `brainURL string` — OpenBrain API base URL.
  - `brainKey string` — OpenBrain API key.
  - `codePath string` — Local code root used for prepared workspaces.
  - `client *http.Client` — HTTP client used for remote and Forge requests.
  - `drainMu sync.Mutex` — Mutex guarding queue-drain operations.
  - `pokeCh chan struct{}` — Channel used to wake the queue runner.
  - `frozen bool` — Whether queue processing is frozen during shutdown.
  - `backoff map[string]time.Time` — pool → paused until
  - `failCount map[string]int` — pool → consecutive fast failures

### RateConfig
- **File:** queue.go
- **Purpose:** RateConfig controls pacing between task dispatches.
- **Fields:**
  - `ResetUTC string` — Daily quota reset time (UTC), e.g. "06:00"
  - `DailyLimit int` — Max requests per day (0 = unknown)
  - `MinDelay int` — Minimum seconds between task starts
  - `SustainedDelay int` — Delay when pacing for full-day use
  - `BurstWindow int` — Hours before reset where burst kicks in
  - `BurstDelay int` — Delay during burst window

### RateLimitInfo
- **File:** review_queue.go
- **Purpose:** RateLimitInfo tracks CodeRabbit rate limit state.
- **Fields:**
  - `Limited bool` — Whether the pool is currently rate-limited.
  - `RetryAt time.Time` — Time when the backoff expires.
  - `Message string` — Human-readable status message.

### RemoteDispatchInput
- **File:** remote.go
- **Purpose:** RemoteDispatchInput dispatches a task to a remote core-agent over HTTP.
- **Fields:**
  - `Host string` — Remote agent host (e.g. "charon", "10.69.69.165:9101")
  - `Repo string` — Target repo
  - `Task string` — What the agent should do
  - `Agent string` — Agent type (default: claude:opus)
  - `Template string` — Prompt template
  - `Persona string` — Persona slug
  - `Org string` — Forge org (default: core)
  - `Variables map[string]string` — Template variables

### RemoteDispatchOutput
- **File:** remote.go
- **Purpose:** RemoteDispatchOutput is the response from a remote dispatch.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Host string` — Remote host handling the request.
  - `Repo string` — Repository name.
  - `Agent string` — Agent name or pool identifier.
  - `WorkspaceDir string` — Workspace directory path.
  - `PID int` — Process ID for the spawned agent.
  - `Error string` — Error message, if the operation failed.

### RemoteStatusInput
- **File:** remote_status.go
- **Purpose:** RemoteStatusInput queries a remote core-agent for workspace status.
- **Fields:**
  - `Host string` — Remote agent host (e.g. "charon")

### RemoteStatusOutput
- **File:** remote_status.go
- **Purpose:** RemoteStatusOutput is the response from a remote status check.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Host string` — Remote host handling the request.
  - `Stats StatusOutput` — Status snapshot returned by the remote host.
  - `Error string` — Error message, if the operation failed.

### ResumeInput
- **File:** resume.go
- **Purpose:** ResumeInput is the input for agentic_resume.
- **Fields:**
  - `Workspace string` — workspace name (e.g. "go-scm-1773581173")
  - `Answer string` — answer to the blocked question (written to ANSWER.md)
  - `Agent string` — override agent type (default: same as original)
  - `DryRun bool` — preview without executing

### ResumeOutput
- **File:** resume.go
- **Purpose:** ResumeOutput is the output for agentic_resume.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Workspace string` — Workspace identifier or path.
  - `Agent string` — Agent name or pool identifier.
  - `PID int` — Process ID for the spawned agent.
  - `OutputFile string` — Path to the captured process output file.
  - `Prompt string` — Rendered prompt content.

### ReviewQueueInput
- **File:** review_queue.go
- **Purpose:** ReviewQueueInput controls the review queue runner.
- **Fields:**
  - `Limit int` — Max PRs to process this run (default: 4)
  - `Reviewer string` — "coderabbit" (default), "codex", or "both"
  - `DryRun bool` — Preview without acting
  - `LocalOnly bool` — Run review locally, don't touch GitHub

### ReviewQueueOutput
- **File:** review_queue.go
- **Purpose:** ReviewQueueOutput reports what happened.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Processed []ReviewResult` — Review results that were processed.
  - `Skipped []string` — Skipped items or skip reason, depending on context.
  - `RateLimit *RateLimitInfo` — Rate-limit information, when present.

### ReviewResult
- **File:** review_queue.go
- **Purpose:** ReviewResult is the outcome of reviewing one repo.
- **Fields:**
  - `Repo string` — Repository name.
  - `Verdict string` — clean, findings, rate_limited, error
  - `Findings int` — Number of findings (0 = clean)
  - `Action string` — merged, fix_dispatched, skipped, waiting
  - `Detail string` — Additional detail about the review result.

### ScanInput
- **File:** scan.go
- **Purpose:** ScanInput is the input for agentic_scan.
- **Fields:**
  - `Org string` — default "core"
  - `Labels []string` — filter by labels (default: agentic, help-wanted, bug)
  - `Limit int` — max issues to return

### ScanIssue
- **File:** scan.go
- **Purpose:** ScanIssue is a single actionable issue.
- **Fields:**
  - `Repo string` — Repository name.
  - `Number int` — Numeric identifier.
  - `Title string` — Title text.
  - `Labels []string` — Label names applied to the issue or pull request.
  - `Assignee string` — Assignee.
  - `URL string` — URL for the item.

### ScanOutput
- **File:** scan.go
- **Purpose:** ScanOutput is the output for agentic_scan.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Count int` — Number of issues returned by the scan.
  - `Issues []ScanIssue` — Issues returned by the scan.

### ShutdownInput
- **File:** shutdown.go
- **Purpose:** ShutdownInput is the input for agentic_dispatch_shutdown.
- **Fields:** none

### ShutdownOutput
- **File:** shutdown.go
- **Purpose:** ShutdownOutput is the output for agentic_dispatch_shutdown.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Running int` — Running value.
  - `Queued int` — Number of queued items.
  - `Message string` — Human-readable status message.

### StatusInput
- **File:** status.go
- **Purpose:** StatusInput is the input for agentic_status.
- **Fields:**
  - `Workspace string` — specific workspace name, or empty for all
  - `Limit int` — max results (default 100)
  - `Status string` — filter: running, completed, failed, blocked

### StatusOutput
- **File:** status.go
- **Purpose:** StatusOutput is the output for agentic_status. Returns stats by default. Only blocked workspaces are listed (they need attention).
- **Fields:**
  - `Total int` — Total number of tracked workspaces.
  - `Running int` — Running value.
  - `Queued int` — Number of queued items.
  - `Completed int` — Number of completed items.
  - `Failed int` — Failed results.
  - `Blocked []BlockedInfo` — List of blocked values.

### WatchInput
- **File:** watch.go
- **Purpose:** WatchInput is the input for agentic_watch.
- **Fields:**
  - `Workspaces []string` — Workspaces to watch. If empty, watches all running/queued workspaces.
  - `PollInterval int` — PollInterval in seconds (default: 5)
  - `Timeout int` — Timeout in seconds (default: 600 = 10 minutes)

### WatchOutput
- **File:** watch.go
- **Purpose:** WatchOutput is the result when all watched workspaces complete.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Completed []WatchResult` — Number of completed items.
  - `Failed []WatchResult` — Failed results.
  - `Duration string` — Duration string for the event or backoff.

### WatchResult
- **File:** watch.go
- **Purpose:** WatchResult describes one completed workspace.
- **Fields:**
  - `Workspace string` — Workspace identifier or path.
  - `Agent string` — Agent name or pool identifier.
  - `Repo string` — Repository name.
  - `Status string` — Current status string.
  - `PRURL string` — Pull request URL.

### WorkspaceStatus
- **File:** status.go
- **Purpose:** WorkspaceStatus represents the current state of an agent workspace.
- **Fields:**
  - `Status string` — running, completed, blocked, failed
  - `Agent string` — gemini, claude, codex
  - `Repo string` — target repo
  - `Org string` — forge org (e.g. "core")
  - `Task string` — task description
  - `Branch string` — git branch name
  - `Issue int` — forge issue number
  - `PID int` — process ID (if running)
  - `StartedAt time.Time` — when dispatch started
  - `UpdatedAt time.Time` — last status change
  - `Question string` — from BLOCKED.md
  - `Runs int` — how many times dispatched/resumed
  - `PRURL string` — pull request URL (after PR created)

## Functions

### AgentName
- **File:** paths.go
- **Signature:** `func AgentName() string`
- **Purpose:** AgentName returns the name of this agent based on hostname. Checks AGENT_NAME env var first.

### CoreRoot
- **File:** paths.go
- **Signature:** `func CoreRoot() string`
- **Purpose:** CoreRoot returns the root directory for core ecosystem files. Checks CORE_WORKSPACE env var first, falls back to ~/Code/.core.

### DefaultBranch
- **File:** paths.go
- **Signature:** `func DefaultBranch(repoDir string) string`
- **Purpose:** DefaultBranch detects the default branch of a repo (main, master, etc.).

### GitHubOrg
- **File:** paths.go
- **Signature:** `func GitHubOrg() string`
- **Purpose:** GitHubOrg returns the GitHub org for mirror operations.

### LocalFs
- **File:** paths.go
- **Signature:** `func LocalFs() *core.Fs`
- **Purpose:** LocalFs returns an unrestricted filesystem instance for use by other packages.

### NewPrep
- **File:** prep.go
- **Signature:** `func NewPrep() *PrepSubsystem`
- **Purpose:** NewPrep creates an agentic subsystem.

### PlansRoot
- **File:** paths.go
- **Signature:** `func PlansRoot() string`
- **Purpose:** PlansRoot returns the root directory for agent plans.

### ReadStatus
- **File:** status.go
- **Signature:** `func ReadStatus(wsDir string) (*WorkspaceStatus, error)`
- **Purpose:** ReadStatus parses the status.json in a workspace directory.

### Register
- **File:** register.go
- **Signature:** `func Register(c *core.Core) core.Result`
- **Purpose:** Register is the service factory for core.WithService. Returns the PrepSubsystem instance — WithService auto-discovers the name from the package path and registers it. Startable/Stoppable/HandleIPCEvents are auto-discovered by RegisterService.

### RegisterHandlers
- **File:** handlers.go
- **Signature:** `func RegisterHandlers(c *core.Core, s *PrepSubsystem)`
- **Purpose:** RegisterHandlers registers the post-completion pipeline as discrete IPC handlers. Each handler listens for a specific message and emits the next in the chain:

### WorkspaceRoot
- **File:** paths.go
- **Signature:** `func WorkspaceRoot() string`
- **Purpose:** WorkspaceRoot returns the root directory for agent workspaces. Checks CORE_WORKSPACE env var first, falls back to ~/Code/.core/workspace.

## Methods

### ConcurrencyLimit.UnmarshalYAML
- **File:** queue.go
- **Signature:** `func (*ConcurrencyLimit) UnmarshalYAML(value *yaml.Node) error`
- **Purpose:** UnmarshalYAML handles both int and map forms.

### PrepSubsystem.DispatchSync
- **File:** dispatch_sync.go
- **Signature:** `func (*PrepSubsystem) DispatchSync(ctx context.Context, input DispatchSyncInput) DispatchSyncResult`
- **Purpose:** DispatchSync preps a workspace, spawns the agent directly (no queue, no concurrency check), and blocks until the agent completes.

### PrepSubsystem.Name
- **File:** prep.go
- **Signature:** `func (*PrepSubsystem) Name() string`
- **Purpose:** Name implements mcp.Subsystem.

### PrepSubsystem.OnShutdown
- **File:** prep.go
- **Signature:** `func (*PrepSubsystem) OnShutdown(ctx context.Context) error`
- **Purpose:** OnShutdown implements core.Stoppable — freezes the queue.

### PrepSubsystem.OnStartup
- **File:** prep.go
- **Signature:** `func (*PrepSubsystem) OnStartup(ctx context.Context) error`
- **Purpose:** OnStartup implements core.Startable — starts the queue runner and registers commands.

### PrepSubsystem.Poke
- **File:** runner.go
- **Signature:** `func (*PrepSubsystem) Poke()`
- **Purpose:** Poke signals the runner to check the queue immediately. Non-blocking — if a poke is already pending, this is a no-op.

### PrepSubsystem.RegisterTools
- **File:** prep.go
- **Signature:** `func (*PrepSubsystem) RegisterTools(server *mcp.Server)`
- **Purpose:** RegisterTools implements mcp.Subsystem.

### PrepSubsystem.SetCore
- **File:** prep.go
- **Signature:** `func (*PrepSubsystem) SetCore(c *core.Core)`
- **Purpose:** SetCore wires the Core framework instance for IPC, Config, and Lock access.

### PrepSubsystem.Shutdown
- **File:** prep.go
- **Signature:** `func (*PrepSubsystem) Shutdown(_ context.Context) error`
- **Purpose:** Shutdown implements mcp.SubsystemWithShutdown.

### PrepSubsystem.StartRunner
- **File:** runner.go
- **Signature:** `func (*PrepSubsystem) StartRunner()`
- **Purpose:** StartRunner begins the background queue runner. Queue is frozen by default — use agentic_dispatch_start to unfreeze, or set CORE_AGENT_DISPATCH=1 to auto-start.

### PrepSubsystem.TestBuildPrompt
- **File:** prep.go
- **Signature:** `func (*PrepSubsystem) TestBuildPrompt(ctx context.Context, input PrepInput, branch, repoPath string) (string, int, int)`
- **Purpose:** TestBuildPrompt exposes buildPrompt for CLI testing.

### PrepSubsystem.TestPrepWorkspace
- **File:** prep.go
- **Signature:** `func (*PrepSubsystem) TestPrepWorkspace(ctx context.Context, input PrepInput) (*mcp.CallToolResult, PrepOutput, error)`
- **Purpose:** TestPrepWorkspace exposes prepWorkspace for CLI testing.


## brain

**Import:** `dappco.re/go/agent/pkg/brain`
**Files:** 6

Package brain provides an MCP subsystem that proxies OpenBrain knowledge
store operations to the Laravel php-agentic backend via the IDE bridge.

## Types

### BrainProvider
- **File:** provider.go
- **Purpose:** BrainProvider wraps the brain Subsystem as a service provider with REST endpoints. It delegates to the same IDE bridge that the MCP tools use.
- **Fields:**
  - `bridge *ide.Bridge` — IDE bridge used to access php-agentic services.
  - `hub *ws.Hub` — WebSocket hub exposed by the provider.

### ConversationInput
- **File:** messaging.go
- **Purpose:** ConversationInput selects the agent thread to load.
- **Fields:**
  - `Agent string` — Agent name or pool identifier.

### ConversationOutput
- **File:** messaging.go
- **Purpose:** ConversationOutput returns a direct message thread with another agent.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Messages []MessageItem` — Conversation or inbox messages.

### DirectSubsystem
- **File:** direct.go
- **Purpose:** DirectSubsystem calls the OpenBrain HTTP API without the IDE bridge.
- **Fields:**
  - `apiURL string` — Base URL for direct OpenBrain HTTP calls.
  - `apiKey string` — API key for direct OpenBrain HTTP calls.
  - `client *http.Client` — HTTP client used for direct requests.

### ForgetInput
- **File:** tools.go
- **Purpose:** ForgetInput is the input for brain_forget.
- **Fields:**
  - `ID string` — Stable identifier.
  - `Reason string` — Reason string supplied with the result.

### ForgetOutput
- **File:** tools.go
- **Purpose:** ForgetOutput is the output for brain_forget.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Forgotten string` — Identifier of the forgotten memory.
  - `Timestamp time.Time` — Timestamp recorded for the event.

### InboxInput
- **File:** messaging.go
- **Purpose:** InboxInput selects which agent inbox to read.
- **Fields:**
  - `Agent string` — Agent name or pool identifier.

### InboxOutput
- **File:** messaging.go
- **Purpose:** InboxOutput returns the latest direct messages for an agent.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Messages []MessageItem` — Conversation or inbox messages.

### ListInput
- **File:** tools.go
- **Purpose:** ListInput is the input for brain_list.
- **Fields:**
  - `Project string` — Project name associated with the request.
  - `Type string` — Type discriminator.
  - `AgentID string` — Agent identifier used by the brain service.
  - `Limit int` — Maximum number of items to return.

### ListOutput
- **File:** tools.go
- **Purpose:** ListOutput is the output for brain_list.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Count int` — Total number of returned items.
  - `Memories []Memory` — Returned memories or memory count, depending on context.

### Memory
- **File:** tools.go
- **Purpose:** Memory is a single memory entry returned by recall or list.
- **Fields:**
  - `ID string` — Stable identifier.
  - `AgentID string` — Agent identifier used by the brain service.
  - `Type string` — Type discriminator.
  - `Content string` — Message or memory content.
  - `Tags []string` — Tag values attached to the memory.
  - `Project string` — Project name associated with the request.
  - `Confidence float64` — Confidence score attached to the memory.
  - `SupersedesID string` — Identifier of the superseded memory.
  - `ExpiresAt string` — Expiration timestamp, when set.
  - `CreatedAt string` — Creation timestamp.
  - `UpdatedAt string` — Last-update timestamp.

### MessageItem
- **File:** messaging.go
- **Purpose:** MessageItem is one inbox or conversation message.
- **Fields:**
  - `ID int` — Stable identifier.
  - `From string` — Message sender.
  - `To string` — Message recipient.
  - `Subject string` — Message subject.
  - `Content string` — Message or memory content.
  - `Read bool` — Whether the message has been marked as read.
  - `CreatedAt string` — Creation timestamp.

### RecallFilter
- **File:** tools.go
- **Purpose:** RecallFilter holds optional filter criteria for brain_recall.
- **Fields:**
  - `Project string` — Project name associated with the request.
  - `Type any` — Type discriminator.
  - `AgentID string` — Agent identifier used by the brain service.
  - `MinConfidence float64` — Minimum confidence required when filtering recalls.

### RecallInput
- **File:** tools.go
- **Purpose:** RecallInput is the input for brain_recall.
- **Fields:**
  - `Query string` — Recall query text.
  - `TopK int` — Maximum number of recall matches to return.
  - `Filter RecallFilter` — Recall filter applied to the query.

### RecallOutput
- **File:** tools.go
- **Purpose:** RecallOutput is the output for brain_recall.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `Count int` — Total number of returned items.
  - `Memories []Memory` — Returned memories or memory count, depending on context.

### RememberInput
- **File:** tools.go
- **Purpose:** RememberInput is the input for brain_remember.
- **Fields:**
  - `Content string` — Message or memory content.
  - `Type string` — Type discriminator.
  - `Tags []string` — Tag values attached to the memory.
  - `Project string` — Project name associated with the request.
  - `Confidence float64` — Confidence score attached to the memory.
  - `Supersedes string` — Identifier of the memory this write supersedes.
  - `ExpiresIn int` — Relative expiry in seconds.

### RememberOutput
- **File:** tools.go
- **Purpose:** RememberOutput is the output for brain_remember.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `MemoryID string` — Identifier of the stored memory.
  - `Timestamp time.Time` — Timestamp recorded for the event.

### SendInput
- **File:** messaging.go
- **Purpose:** SendInput sends a direct message to another agent.
- **Fields:**
  - `To string` — Message recipient.
  - `Content string` — Message or memory content.
  - `Subject string` — Message subject.

### SendOutput
- **File:** messaging.go
- **Purpose:** SendOutput reports the created direct message.
- **Fields:**
  - `Success bool` — Whether the operation succeeded.
  - `ID int` — Stable identifier.
  - `To string` — Message recipient.

### Subsystem
- **File:** brain.go
- **Purpose:** Subsystem proxies brain_* MCP tools through the shared IDE bridge.
- **Fields:**
  - `bridge *ide.Bridge` — IDE bridge used to proxy requests into php-agentic.

## Functions

### New
- **File:** brain.go
- **Signature:** `func New(bridge *ide.Bridge) *Subsystem`
- **Purpose:** New creates a bridge-backed brain subsystem.

### NewDirect
- **File:** direct.go
- **Signature:** `func NewDirect() *DirectSubsystem`
- **Purpose:** NewDirect creates a direct HTTP brain subsystem.

### NewProvider
- **File:** provider.go
- **Signature:** `func NewProvider(bridge *ide.Bridge, hub *ws.Hub) *BrainProvider`
- **Purpose:** NewProvider creates a brain provider that proxies to Laravel via the IDE bridge. The WS hub is used to emit brain events. Pass nil for hub if not needed.

### Register
- **File:** register.go
- **Signature:** `func Register(c *core.Core) core.Result`
- **Purpose:** Register is the service factory for core.WithService. Returns the DirectSubsystem — WithService auto-registers it.

## Methods

### BrainProvider.BasePath
- **File:** provider.go
- **Signature:** `func (*BrainProvider) BasePath() string`
- **Purpose:** BasePath implements api.RouteGroup.

### BrainProvider.Channels
- **File:** provider.go
- **Signature:** `func (*BrainProvider) Channels() []string`
- **Purpose:** Channels implements provider.Streamable.

### BrainProvider.Describe
- **File:** provider.go
- **Signature:** `func (*BrainProvider) Describe() []api.RouteDescription`
- **Purpose:** Describe implements api.DescribableGroup.

### BrainProvider.Element
- **File:** provider.go
- **Signature:** `func (*BrainProvider) Element() provider.ElementSpec`
- **Purpose:** Element implements provider.Renderable.

### BrainProvider.Name
- **File:** provider.go
- **Signature:** `func (*BrainProvider) Name() string`
- **Purpose:** Name implements api.RouteGroup.

### BrainProvider.RegisterRoutes
- **File:** provider.go
- **Signature:** `func (*BrainProvider) RegisterRoutes(rg *gin.RouterGroup)`
- **Purpose:** RegisterRoutes implements api.RouteGroup.

### DirectSubsystem.Name
- **File:** direct.go
- **Signature:** `func (*DirectSubsystem) Name() string`
- **Purpose:** Name returns the MCP subsystem name.

### DirectSubsystem.RegisterMessagingTools
- **File:** messaging.go
- **Signature:** `func (*DirectSubsystem) RegisterMessagingTools(server *mcp.Server)`
- **Purpose:** RegisterMessagingTools adds direct agent messaging tools to an MCP server.

### DirectSubsystem.RegisterTools
- **File:** direct.go
- **Signature:** `func (*DirectSubsystem) RegisterTools(server *mcp.Server)`
- **Purpose:** RegisterTools adds the direct OpenBrain tools to an MCP server.

### DirectSubsystem.Shutdown
- **File:** direct.go
- **Signature:** `func (*DirectSubsystem) Shutdown(_ context.Context) error`
- **Purpose:** Shutdown closes the direct subsystem without additional cleanup.

### Subsystem.Name
- **File:** brain.go
- **Signature:** `func (*Subsystem) Name() string`
- **Purpose:** Name returns the MCP subsystem name.

### Subsystem.RegisterTools
- **File:** brain.go
- **Signature:** `func (*Subsystem) RegisterTools(server *mcp.Server)`
- **Purpose:** RegisterTools adds the bridge-backed brain tools to an MCP server.

### Subsystem.Shutdown
- **File:** brain.go
- **Signature:** `func (*Subsystem) Shutdown(_ context.Context) error`
- **Purpose:** Shutdown closes the subsystem without additional cleanup.


## lib

**Import:** `dappco.re/go/agent/pkg/lib`
**Files:** 1

Package lib provides embedded content for agent dispatch.
Prompts, tasks, flows, personas, and workspace templates.

Structure:

	prompt/      — System prompts (HOW to work)
	task/        — Structured task plans (WHAT to do)
	task/code/   — Code-specific tasks (review, refactor, etc.)
	flow/        — Build/release workflows per language/tool
	persona/     — Domain/role system prompts (WHO you are)
	workspace/   — Agent workspace templates (WHERE to work)

Usage:

	r := lib.Prompt("coding")        // r.Value.(string)
	r := lib.Task("code/review")     // r.Value.(string)
	r := lib.Persona("secops/dev")   // r.Value.(string)
	r := lib.Flow("go")              // r.Value.(string)
	lib.ExtractWorkspace("default", "/tmp/ws", data)

## Types

### Bundle
- **File:** lib.go
- **Purpose:** Bundle holds a task's main content plus companion files.
- **Fields:**
  - `Main string` — Primary bundled document content.
  - `Files map[string]string` — Number of files or bundled file contents, depending on context.

### WorkspaceData
- **File:** lib.go
- **Purpose:** WorkspaceData is the data passed to workspace templates.
- **Fields:**
  - `Repo string` — Repository name.
  - `Branch string` — Branch name.
  - `Task string` — Task description.
  - `Agent string` — Agent name or pool identifier.
  - `Language string` — Detected repository language.
  - `Prompt string` — Rendered prompt content.
  - `Persona string` — Persona slug injected into the workspace template.
  - `Flow string` — Workflow content or slug injected into the workspace template.
  - `Context string` — Additional context injected into a workspace template.
  - `Recent string` — Recent-change context injected into a workspace template.
  - `Dependencies string` — Dependency context injected into a workspace template.
  - `Conventions string` — Coding-convention guidance injected into a workspace template.
  - `RepoDescription string` — Repository description injected into the workspace template.
  - `BuildCmd string` — Build command injected into workspace templates.
  - `TestCmd string` — Test command injected into workspace templates.

## Functions

### ExtractWorkspace
- **File:** lib.go
- **Signature:** `func ExtractWorkspace(tmplName, targetDir string, data *WorkspaceData) error`
- **Purpose:** ExtractWorkspace creates an agent workspace from a template. Template names: "default", "security", "review".

### Flow
- **File:** lib.go
- **Signature:** `func Flow(slug string) core.Result`
- **Purpose:** Flow reads a build/release workflow by slug.

### ListFlows
- **File:** lib.go
- **Signature:** `func ListFlows() []string`
- **Purpose:** Lists embedded workflow slugs from the flow bundle.

### ListPersonas
- **File:** lib.go
- **Signature:** `func ListPersonas() []string`
- **Purpose:** Lists embedded persona paths from the persona bundle.

### ListPrompts
- **File:** lib.go
- **Signature:** `func ListPrompts() []string`
- **Purpose:** Lists embedded prompt slugs from the prompt bundle.

### ListTasks
- **File:** lib.go
- **Signature:** `func ListTasks() []string`
- **Purpose:** Lists embedded task slugs by walking the task bundle.

### ListWorkspaces
- **File:** lib.go
- **Signature:** `func ListWorkspaces() []string`
- **Purpose:** Lists embedded workspace template names from the workspace bundle.

### Persona
- **File:** lib.go
- **Signature:** `func Persona(path string) core.Result`
- **Purpose:** Persona reads a domain/role persona by path.

### Prompt
- **File:** lib.go
- **Signature:** `func Prompt(slug string) core.Result`
- **Purpose:** Prompt reads a system prompt by slug.

### Task
- **File:** lib.go
- **Signature:** `func Task(slug string) core.Result`
- **Purpose:** Task reads a structured task plan by slug. Tries .md, .yaml, .yml.

### TaskBundle
- **File:** lib.go
- **Signature:** `func TaskBundle(slug string) core.Result`
- **Purpose:** TaskBundle reads a task and its companion files.

### Template
- **File:** lib.go
- **Signature:** `func Template(slug string) core.Result`
- **Purpose:** Template tries Prompt then Task (backwards compat).

## Methods

No exported methods.


## messages

**Import:** `dappco.re/go/agent/pkg/messages`
**Files:** 1

Package messages defines IPC message types for inter-service communication
within core-agent. Services emit these via c.ACTION() and handle them via
c.RegisterAction(). No service imports another — they share only these types.

	c.ACTION(messages.AgentCompleted{Agent: "codex", Repo: "go-io", Status: "completed"})

## Types

### AgentCompleted
- **File:** messages.go
- **Purpose:** AgentCompleted is broadcast when a subagent process exits.
- **Fields:**
  - `Agent string` — Agent name or pool identifier.
  - `Repo string` — Repository name.
  - `Workspace string` — Workspace identifier or path.
  - `Status string` — completed, failed, blocked

### AgentStarted
- **File:** messages.go
- **Purpose:** AgentStarted is broadcast when a subagent process is spawned.
- **Fields:**
  - `Agent string` — Agent name or pool identifier.
  - `Repo string` — Repository name.
  - `Workspace string` — Workspace identifier or path.

### HarvestComplete
- **File:** messages.go
- **Purpose:** HarvestComplete is broadcast when a workspace branch is ready for review.
- **Fields:**
  - `Repo string` — Repository name.
  - `Branch string` — Branch name.
  - `Files int` — Number of files or bundled file contents, depending on context.

### HarvestRejected
- **File:** messages.go
- **Purpose:** HarvestRejected is broadcast when a workspace fails safety checks (binaries, size).
- **Fields:**
  - `Repo string` — Repository name.
  - `Branch string` — Branch name.
  - `Reason string` — Reason string supplied with the result.

### InboxMessage
- **File:** messages.go
- **Purpose:** InboxMessage is broadcast when new inter-agent messages arrive.
- **Fields:**
  - `New int` — Number of newly observed messages.
  - `Total int` — Total number of items observed.

### PRCreated
- **File:** messages.go
- **Purpose:** PRCreated is broadcast after a PR is auto-created on Forge.
- **Fields:**
  - `Repo string` — Repository name.
  - `Branch string` — Branch name.
  - `PRURL string` — Pull request URL.
  - `PRNum int` — Pull request number.

### PRMerged
- **File:** messages.go
- **Purpose:** PRMerged is broadcast after a PR is auto-verified and merged.
- **Fields:**
  - `Repo string` — Repository name.
  - `PRURL string` — Pull request URL.
  - `PRNum int` — Pull request number.

### PRNeedsReview
- **File:** messages.go
- **Purpose:** PRNeedsReview is broadcast when auto-merge fails and human attention is needed.
- **Fields:**
  - `Repo string` — Repository name.
  - `PRURL string` — Pull request URL.
  - `PRNum int` — Pull request number.
  - `Reason string` — Reason string supplied with the result.

### PokeQueue
- **File:** messages.go
- **Purpose:** PokeQueue signals the runner to drain the queue immediately.
- **Fields:** none

### QAResult
- **File:** messages.go
- **Purpose:** QAResult is broadcast after QA runs on a completed workspace.
- **Fields:**
  - `Workspace string` — Workspace identifier or path.
  - `Repo string` — Repository name.
  - `Passed bool` — Whether QA passed.
  - `Output string` — Command output or QA output text.

### QueueDrained
- **File:** messages.go
- **Purpose:** QueueDrained is broadcast when running=0 and queued=0 (genuinely empty).
- **Fields:**
  - `Completed int` — Number of completed items.

### RateLimitDetected
- **File:** messages.go
- **Purpose:** RateLimitDetected is broadcast when fast failures trigger agent pool backoff.
- **Fields:**
  - `Pool string` — Agent pool that triggered the event.
  - `Duration string` — Duration string for the event or backoff.

## Functions

No exported functions.

## Methods

No exported methods.


## monitor

**Import:** `dappco.re/go/agent/pkg/monitor`
**Files:** 4

Package monitor provides a background subsystem that watches the ecosystem
and pushes notifications to connected MCP clients.

Checks performed on each tick:
  - Agent completions: scans workspace for newly completed agents
  - Repo drift: checks forge for repos with unpushed/unpulled changes
  - Inbox: checks for unread agent messages

## Types

### ChangedRepo
- **File:** sync.go
- **Purpose:** ChangedRepo is a repo that has new commits.
- **Fields:**
  - `Repo string` — Repository name.
  - `Branch string` — Branch name.
  - `SHA string` — Commit SHA.

### ChannelNotifier
- **File:** monitor.go
- **Purpose:** ChannelNotifier pushes events to connected MCP sessions.
- **Methods:**
  - `ChannelSend(ctx context.Context, channel string, data any)` — Sends a payload to a named notifier channel.

### CheckinResponse
- **File:** sync.go
- **Purpose:** CheckinResponse is what the API returns for an agent checkin.
- **Fields:**
  - `Changed []ChangedRepo` — Repos that have new commits since the agent's last checkin.
  - `Timestamp int64` — Server timestamp — use as "since" on next checkin.

### Options
- **File:** monitor.go
- **Purpose:** Options configures the monitor interval.
- **Fields:**
  - `Interval time.Duration` — Interval between checks (default: 2 minutes)

### Subsystem
- **File:** monitor.go
- **Purpose:** Subsystem implements mcp.Subsystem for background monitoring.
- **Fields:**
  - `core *core.Core` — Core framework instance for IPC
  - `server *mcp.Server` — MCP server used to register monitor resources.
  - `notifier ChannelNotifier` — Channel notification relay, uses c.ACTION()
  - `interval time.Duration` — Interval between monitor scans.
  - `cancel context.CancelFunc` — Cancellation function for the monitor loop.
  - `wg sync.WaitGroup` — WaitGroup tracking monitor goroutines.
  - `lastCompletedCount int` — Track last seen state to only notify on changes
  - `seenCompleted map[string]bool` — workspace names we've already notified about
  - `seenRunning map[string]bool` — workspace names we've already sent start notification for
  - `completionsSeeded bool` — true after first completions check
  - `lastInboxMaxID int` — highest message ID seen
  - `inboxSeeded bool` — true after first inbox check
  - `lastSyncTimestamp int64` — Unix timestamp of the last repo-sync check.
  - `mu sync.Mutex` — Mutex guarding monitor state.
  - `poke chan struct{}` — Event-driven poke channel — dispatch goroutine sends here on completion

## Functions

### New
- **File:** monitor.go
- **Signature:** `func New(opts ...Options) *Subsystem`
- **Purpose:** New creates a monitor subsystem.

### Register
- **File:** register.go
- **Signature:** `func Register(c *core.Core) core.Result`
- **Purpose:** Register is the service factory for core.WithService. Returns the monitor Subsystem — WithService auto-registers it.

## Methods

### Subsystem.Name
- **File:** monitor.go
- **Signature:** `func (*Subsystem) Name() string`
- **Purpose:** Name returns the subsystem identifier used by MCP registration.

### Subsystem.OnShutdown
- **File:** monitor.go
- **Signature:** `func (*Subsystem) OnShutdown(ctx context.Context) error`
- **Purpose:** OnShutdown implements core.Stoppable — stops the monitoring loop.

### Subsystem.OnStartup
- **File:** monitor.go
- **Signature:** `func (*Subsystem) OnStartup(ctx context.Context) error`
- **Purpose:** OnStartup implements core.Startable — starts the monitoring loop.

### Subsystem.Poke
- **File:** monitor.go
- **Signature:** `func (*Subsystem) Poke()`
- **Purpose:** Poke triggers an immediate check cycle. Prefer AgentStarted/AgentCompleted..

### Subsystem.RegisterTools
- **File:** monitor.go
- **Signature:** `func (*Subsystem) RegisterTools(server *mcp.Server)`
- **Purpose:** RegisterTools binds the monitor resource to an MCP server.

### Subsystem.SetCore
- **File:** monitor.go
- **Signature:** `func (*Subsystem) SetCore(c *core.Core)`
- **Purpose:** SetCore wires the Core framework instance and registers IPC handlers.

### Subsystem.SetNotifier
- **File:** monitor.go
- **Signature:** `func (*Subsystem) SetNotifier(n ChannelNotifier)`
- **Purpose:** SetNotifier wires up channel event broadcasting. Deprecated: Phase 3 replaces this with c.ACTION(messages.X{}).

### Subsystem.Shutdown
- **File:** monitor.go
- **Signature:** `func (*Subsystem) Shutdown(_ context.Context) error`
- **Purpose:** Shutdown stops the monitoring loop and waits for it to exit.

### Subsystem.Start
- **File:** monitor.go
- **Signature:** `func (*Subsystem) Start(ctx context.Context)`
- **Purpose:** Start begins the background monitoring loop after MCP startup.


## setup

**Import:** `dappco.re/go/agent/pkg/setup`
**Files:** 3

Package setup provides workspace setup and scaffolding using lib templates.

## Types

### Command
- **File:** config.go
- **Purpose:** Command is a named runnable command.
- **Fields:**
  - `Name string` — Name of the item.
  - `Run string` — Command line to run.

### ConfigData
- **File:** config.go
- **Purpose:** ConfigData holds the data passed to config templates.
- **Fields:**
  - `Name string` — Name of the item.
  - `Description string` — Human-readable description.
  - `Type string` — Type discriminator.
  - `Module string` — Detected Go module or project module name.
  - `Repository string` — Repository remote in owner/name form.
  - `GoVersion string` — Detected Go version.
  - `Targets []Target` — Configured build targets.
  - `Commands []Command` — Generated commands or command definitions.
  - `Env map[string]string` — Environment variables included in generated config.

### Options
- **File:** setup.go
- **Purpose:** Options controls setup behaviour.
- **Fields:**
  - `Path string` — Target directory (default: cwd)
  - `DryRun bool` — Preview only, don't write
  - `Force bool` — Overwrite existing files
  - `Template string` — Workspace template or compatibility alias (default, review, security, agent, go, php, gui, auto)

### ProjectType
- **File:** detect.go
- **Purpose:** ProjectType identifies what kind of project lives at a path.
- **Underlying Type:** `string`

### Target
- **File:** config.go
- **Purpose:** Target is a build target (os/arch pair).
- **Fields:**
  - `OS string` — Target operating system.
  - `Arch string` — Target CPU architecture.

## Functions

### Detect
- **File:** detect.go
- **Signature:** `func Detect(path string) ProjectType`
- **Purpose:** Detect identifies the project type from files present at the given path.

### DetectAll
- **File:** detect.go
- **Signature:** `func DetectAll(path string) []ProjectType`
- **Purpose:** DetectAll returns all project types found at the path (polyglot repos).

### GenerateBuildConfig
- **File:** config.go
- **Signature:** `func GenerateBuildConfig(path string, projType ProjectType) (string, error)`
- **Purpose:** GenerateBuildConfig renders a build.yaml for the detected project type.

### GenerateTestConfig
- **File:** config.go
- **Signature:** `func GenerateTestConfig(projType ProjectType) (string, error)`
- **Purpose:** GenerateTestConfig renders a test.yaml for the detected project type.

### Run
- **File:** setup.go
- **Signature:** `func Run(opts Options) error`
- **Purpose:** Run performs the workspace setup at the given path. It detects the project type, generates .core/ configs, and optionally scaffolds a workspace from a dir template.

## Methods

No exported methods.