GEWU/docs/architecture/LOCAL_AGENT.md

GEWU local agent

13 October 2026. Owner requirement: a custom local agent built like the agents in the RESEARCH workspaces. Delivery form confirmed by inspecting Winnow in SCAR and Praxis in CV: a workspace profile, shared protocols, modular skills and coordinating pipeline instructions executed by an existing host application.

Architecture decision

Ship a GEWU research-agent pack that runs inside a supported local agent host. The host supplies reasoning, model access and tool execution. GEWU supplies its role, task-specific skills, pipeline procedures and MCP connection contract. A new standalone agent runtime is outside this addition.

The pack is a first-class GEWU client and follows the same permissions as other clients. The knowledge service remains independent: it validates proposals, applies acceptance policy and stores records; the agent interprets sources and drafts knowledge. Reading and evidence navigation continue when no agent is running.

Local execution describes where the host and working files live. A configured cloud model may still receive content. Offline reasoning requires a host with a configured local model; neither the pack nor a local folder guarantees that data stays on the computer. Keep model/provider selection in the host configuration and record the actual model where available.

Source and installation boundary

The source pack lives at agents/gewu in this repository. Its own AGENTS.md defines the research role; it is not the development repository's global persona. This avoids turning every coding session into a research ingestion session.

The intended installed layout resembles the RESEARCH workspaces:

<research-workspace>/
  AGENTS.md                 # thin discovery pointer to canonical profile
  CLAUDE.md                 # thin discovery pointer for Claude Code / Claude Desktop
  .agents/
    AGENTS.md               # GEWU role and routing
    CLAUDE.md               # Claude harness pointer
    manifest.json           # pack/skill/pipeline versions and readiness
    protocols/              # shared evidence, scope and proposal rules
    skills/<name>/SKILL.md
    pipelines/              # coordinating procedures and checkpoint fields
  Inbox/                    # explicitly selected local source inputs
  Drafts/                   # unaccepted draft artifacts
  Runs/                     # private local checkpoints/receipts

The checked-in source pack can be linked or installed into the canonical .agents directory. Host-specific configuration/pointers and a copy fallback must preserve other installed skills and agent profiles. A partial single-skill copy must also include its referenced protocols/pipelines. Do not overwrite an existing root persona or claim host discovery merely because files exist. No host configuration, symlink or user-global installation is performed by this change.

The live reference inspection found SCAR .agents points to .opencode; CV owns .agents directly. Both use workspace rules and reusable skills. GEWU adopts the organization, while changing their direct-file contribution behavior to its MCP proposal contract. Source reads were limited to profiles, skill templates and representative pipelines; their runtime behavior was not retested.

Responsibilities and replaceable modules

Part	Owns	Replacement boundary
Agent profile	Role, routing, project context and collaboration behavior	Update profile version without copying workflow logic into it.
Protocols	Shared evidence, scope and contribution guidance	Referenced by concern; authoritative server validation still lives in service code.
Skills	Ingest, retrieve, curate or synthesize one coherent kind of task	Versioned inputs/outputs, tool needs and acceptance criteria.
Pipelines	Order skills/stages, identify checkpoints, route corrections and report coverage	Separate files reference skills; a changed coordinator need not rewrite every skill.
Host adapter	Discovery, permitted tools and model/runtime configuration	Preserve the same public skill and MCP contracts across hosts.
Local connector	Safe file transfer, MCP transport and diagnostics	Shared connector contract; contains no semantic decision authority.

The modularity protocol applies to all these parts. Pipeline files are procedures interpreted by the host agent, not an executable scheduler or durable engine. MCP run records and receipts provide durable service-side progress. Local checkpoints support recovery but cannot prove acceptance.

Initial workflows

Skill	Pipeline	Output
kb-ingest	Context -> source capture -> triage -> evidence-bound extraction -> support assessment -> proposal -> receipt	Accepted IDs/receipts, held drafts, coverage/skips and actionable findings.
kb-query	Scope -> retrieve -> inspect evidence -> bounded answer	Cited answer with scope, as-of dates, uncertainty and omissions; no writes.
kb-curate	Scoped audit -> inspect candidates -> propose corrections/relations -> receipts	Traceable changes or a report, preserving disagreements and old revisions.
kb-synthesize	Accepted inputs -> dependency inventory -> compare/compose -> evidence audit -> optional proposal	Labeled local synthesis draft, or accepted synthesis after a real receipt.

The four skills are instruction artifacts, and the service has authenticated Streamable HTTP reads and contribution tools. The gewu-connector stdio program bridges explicitly selected local files to that service without exposing file bytes or credentials in model-visible tool responses. It is launched with one or more stable file IDs and paths, plus a service URL; the operator supplies GEWU_TOKEN through the host's protected environment rather than a command-line argument. The connector requires HTTPS for non-loopback services and stores resumable upload checkpoints in a private state file. The pack manifest is bound to generated wire schemas and now has a reversible workspace installer, but host MCP configuration, native client workflows and remote deployment remain unqualified. The authenticated source_capture_url MCP operation is enabled only when the operator configures the exact public-host allowlist in GEWU_FETCH_ALLOWED_HOSTS; URL and selected-file intake support UTF-8 text, Markdown, HTML visible-text extraction and PDF. Linux PDF extraction runs inside bubblewrap; scanned PDFs return an explicit no-text result, and Windows/macOS parsing remain unqualified.

Run and resume contract

At run start, record local run ID, authenticated service/agent identity when connected, explicit scope, task objective, pack/skill/pipeline versions and content hashes, host/model label, input hashes and budgets. Resolve tools and schemas from service diagnostics. Unsupported tools or schemas produce a clear blocked stage. Stage records name their inputs, outputs, disposition and last durable receipt.

For a connected run, service run identity, proposal revisions and acceptance receipts are authoritative. Resume queries them before retrying an uncertain upload/proposal result. Model output is not deterministic: preserve completed output artifacts and their hashes rather than asking the model to regenerate the same content and assuming identical IDs.

Pin the installed pack snapshot for an active run. If that version is unavailable after an upgrade, pause with a compatibility finding or explicitly start a successor run. Reuse previous outputs only when their hashes, evidence bindings and new stage contracts still hold; revalidate downstream stages after changes. Install/version manifests alone cannot enforce this in arbitrary hosts; native workflow tests must demonstrate it.

The pack manifest supplies per-module implementation and instruction-contract versions, dependencies, compatible checkpoint contracts and file hashes for the profile, shared protocols, skills and pipelines. Run checkpoints retain the snapshot digest and resolved module IDs/contracts/hashes. Its service-capability requirements remain explicitly unbound until wire schemas exist; empty capability arrays are not a declaration of compatibility. The draft checkpoint fields and snapshot calculation are specified in the pack README.

A pipeline has a bounded work/correction budget, explicit coverage and a resumable stop. Two unchanged validation failures are a default stop for diagnosis, not permission to relax checks. Network uncertainty triggers status lookup, not a fresh proposal identity. Protected decisions leave the agent workflow for the separate human owner client. No continuous watcher, automatic external messaging or unbounded research loop is introduced.

Acceptance and sequencing

First finish the service/tool contracts, then install the pack into a disposable research workspace and run a complete ingestion/read flow with the selected pilot host. Verify invalid-evidence rejection, uncertain-result retry, run resumption, same-agent assessment attribution and shared-source reuse. Query must still work with a read-only credential.

Before full-v1 client claims, repeat the relevant workflow with Codex, Claude, Antigravity and OpenCode on the declared platform matrix. The custom profile is an additional deliverable using those hosts, not an additional fifth runtime. Synthesis/advanced curation remain under their existing P1 service feature priorities; pack files do not promote those features to implemented P0.

Record structural skill validation separately from installed discovery, tool connection, semantic quality and end-to-end acceptance. No live client, server or model workflow has passed as part of this design addition.