FPF Agent Stack
Bounded Context: Offline AI Agent Runtime
1. Context
Problem. Cloud LLM APIs leak private data, incur per-token costs, and require network connectivity.
Solution. An embedded, offline agent runtime with auditable execution and tri-state safety guards.
Scope. Local development, private automation, air-gapped environments.
2. Intent (L-PROJ-*)
L-PROJ-01: Core Capabilities
| Capability | Description |
|---|---|
| Embedded Model | Qwen 2.5 0.5B Instruct via Transformers.js — no API keys, no network |
| MCP Server | Exposes skills as tools via Model Context Protocol (Stdio) |
| AgentFS | Copy-on-write sandbox for safe, auditable file operations |
| Guard | Tri-state validation: pass / degrade / abstain |
| Skills | Dynamic loading from core/skills/ with L/A/D/E contracts |
L-PROJ-02: Project Structure (FPF E.4 Compliant)
fpf-agent-stack/
├── core/ # CANON: Normative contracts
│ └── skills/ # L/A/D/E skill definitions
│ ├── file-ops/
│ └── repo-search/
├── src/ # TOOLING: Implementation
│ ├── cli.ts
│ ├── mcp-server.ts
│ ├── model-gateway.ts
│ ├── guard.ts
│ └── agent-fs.ts
├── test/ # TOOLING: Verification
│ └── bdd/
│ └── features/
└── docs/ # PEDAGOGY: Rationale & tutorials
└── *.md
3. Archetypal Grounding
U.System Example: AgentFS Session
# Start isolated session
node dist/src/cli.js start-session ./my-project
# All writes go to session layer, host untouched
node dist/src/cli.js write <session> file.txt "content"
# Audit trail available
node dist/src/cli.js audit <session>
U.Episteme Example: Skill Contract
# core/skills/file-ops/SKILL.md
## L-TOOL-01: write_file
Write text content to a file path within workspace.
## A-TOOL-01: Admissibility
- Predicate: Active AgentFS session required
- Evidence: session_id
## D-TOOL-01: Duties
- Writes isolated to session layer
- Text content only (no binary)
## E-TOOL-01: Evidence
- Logged in AgentFS audit log
4. Getting Started
Prerequisites
- Node.js 20+ (LTS)
- 8GB RAM minimum
Setup
npm install
npm run build
Run
# Start MCP server
npm start
# Run tests
npm test
5. Conformance Checklist
| ID | Requirement | Verification |
|---|---|---|
| CC-PROJ-01 | Runs without network | npm start succeeds offline |
| CC-PROJ-02 | Model loads <30s | Manual timing on 8GB machine |
| CC-PROJ-03 | File writes sandboxed | npm test — @agentfs green |
| CC-PROJ-04 | Unknown tools abstain | npm test — @guard green |
6. Relations
Builds on. FPF L/A/D/E pattern, MCP specification, Transformers.js.
Constrains. All skill implementations must follow SKILL.md template.
Coordinates with. Technical-Choices.md, Development-Plan.md, Architecture-Comparison.md.
