From e034afcb829d05d977467238c049415c3fdd9378 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Mon, 9 Mar 2026 08:12:02 +0900 Subject: [PATCH 1/2] docs: update concept page with architecture diagram and fix broken links - Add 5-layer architecture diagram from README - Add design philosophy note about existing standards - Fix 8 broken LinkCard hrefs to point to existing pages - Remove links to non-existent pages (context-windows, delegations, memory, checkpoints, container-isolation, env-vars-secrets) - Add links to runtime, boundary-model, sandbox-integration, and isolation-by-design pages - Improve LinkCard descriptions Co-Authored-By: Claude Opus 4.6 --- docs/understanding-perstack/concept.mdx | 50 +++++++++++++++++-------- 1 file changed, 34 insertions(+), 16 deletions(-) diff --git a/docs/understanding-perstack/concept.mdx b/docs/understanding-perstack/concept.mdx index 47cc8895..58e35c0b 100644 --- a/docs/understanding-perstack/concept.mdx +++ b/docs/understanding-perstack/concept.mdx @@ -11,40 +11,58 @@ Perstack is built on a concept called **Expert Stack** — the harness that enab > [!NOTE] > The name "Perstack" combines the Latin word "perītus" (meaning "expert") with "stack". Perstack = Expert Stack. -## Expert Stack +## Expert Stack -Perstack organizes the complexity of micro-agents harness design into a simple stack model: +An agent harness needs a broad set of capabilities — almost like an operating system. Perstack organizes them into a simple stack with clear separation of concerns: + +``` +┌──────────────────────────────────────────────────────────────────-┐ +│ Interface │ +│ CLI · Event streaming · Programmatic API │ +├──────────────────────────────────────────────────────────────────-┤ +│ Runtime │ +│ Agentic loop · Event-sourcing · Checkpointing · Tool use │ +├──────────────────────────────────────────────────────────────────-┤ +│ Context │ +│ System prompts · Prompt caching · AgenticRAG · Extended thinking │ +├──────────────────────────────────────────────────────────────────-┤ +│ Definition │ +│ Multi-agent topology · MCP skills · Provider abstraction │ +├──────────────────────────────────────────────────────────────────-┤ +│ Infrastructure │ +│ Sandbox isolation · Workspace boundary · Secret management │ +└──────────────────────────────────────────────────────────────────-┘ +``` + +Most of the features above are not new ideas. Perstack takes the usual harness building blocks — tool use, delegation, checkpointing, prompt caching, etc. — makes them easy to operate, puts them on top of standards you already know (MCP, TOML, Docker, SSE), and ships them as one runtime. Where cost or operational burden demands it, Perstack introduces its own take — micro-agents being the first example. ### Definition - Purpose-specific micro-agents. - MCP tools (file ops, exec, custom MCP servers). - LLM providers and models. - Declarative definition of experts, skills, and providers. + Purpose-specific micro-agents with a single responsibility. + MCP tools — file ops, exec, custom MCP servers. + LLM providers and models. + Declarative definition of experts, skills, and providers. ### Context - The context in which experts operate. - The shared workspace in which experts operate. - The delegation of tasks to other experts. - The memory of the expert stack. + The shared filesystem where experts collaborate. ### Runtime - The event-sourcing of the expert stack. - The checkpoints of the expert stack. - The skill management of the expert stack. + Step-level events for full execution observability. + Dynamic skill lifecycle — connect, discover, execute, disconnect. + State machine, agentic loop, and tool execution. ### Infrastructure - The container isolation of the expert stack. - The workspace boundaries of the expert stack. - The env vars/secrets of the expert stack. + Workspace boundaries, path validation, and traversal prevention. + Container isolation and infrastructure-level security. + Environment sandboxing, secret management, and exec protection. From 2f070acfb5650f9f7c48ed04cbfc6e4e467e93db Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Mon, 9 Mar 2026 08:14:18 +0900 Subject: [PATCH 2/2] docs: align concept card sections with architecture diagram layers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Interface layer cards (CLI, runtime embedding, observability) - Reorder sections to match diagram: Interface → Runtime → Context → Definition → Infrastructure - Add one-line description per layer - Add State management, Error handling, Deployment cards - Rewrite all card descriptions to be specific and concrete Co-Authored-By: Claude Opus 4.6 --- docs/understanding-perstack/concept.mdx | 45 ++++++++++++++++++------- 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/docs/understanding-perstack/concept.mdx b/docs/understanding-perstack/concept.mdx index 58e35c0b..9d6f02ac 100644 --- a/docs/understanding-perstack/concept.mdx +++ b/docs/understanding-perstack/concept.mdx @@ -36,33 +36,54 @@ An agent harness needs a broad set of capabilities — almost like an operating Most of the features above are not new ideas. Perstack takes the usual harness building blocks — tool use, delegation, checkpointing, prompt caching, etc. — makes them easy to operate, puts them on top of standards you already know (MCP, TOML, Docker, SSE), and ships them as one runtime. Where cost or operational burden demands it, Perstack introduces its own take — micro-agents being the first example. -### Definition +### Interface + +The top layer exposes Perstack to users and applications. - Purpose-specific micro-agents with a single responsibility. - MCP tools — file ops, exec, custom MCP servers. - LLM providers and models. - Declarative definition of experts, skills, and providers. + Interactive TUI (`start`), headless JSON output (`run`), log inspection, and expert management. + Embed the runtime directly in TypeScript apps for serverless and custom integrations. + Real-time activity log, token metrics, and delegation tree. + + +### Runtime + +The execution engine that drives the agentic loop. + + + 9-state machine — generate, call tools, delegate, resolve, and finish. + Step-level event-sourcing for full execution observability and replay. + Checkpoints, resume, and job hierarchy. + Dynamic skill lifecycle — connect, discover tools, execute, disconnect. ### Context +What each expert sees and knows during execution. + - The shared filesystem where experts collaborate. + The shared filesystem where experts collaborate — not conversation history. + Retries, provider-specific error normalization, and retryability detection. -### Runtime +### Definition + +How you declare what experts do and how they collaborate. - Step-level events for full execution observability. - Dynamic skill lifecycle — connect, discover, execute, disconnect. - State machine, agentic loop, and tool execution. + Purpose-specific micro-agents with a single responsibility. + Declarative config — experts, skills, providers, and global defaults. + MCP tools — file ops, exec, custom MCP servers. + LLM providers, models, and model tier selection. ### Infrastructure +Isolation and security boundaries that make agents safe to operate. + - Workspace boundaries, path validation, and traversal prevention. - Container isolation and infrastructure-level security. + Container isolation with Docker — multi-arch, non-root, ~74 MB. + Workspace boundaries, path validation, and symlink traversal prevention. Environment sandboxing, secret management, and exec protection. + Container images, `perstack install`, and production deployment patterns.