@mono-agent/agent-app 0.1.0 → 0.2.1

package/skills/mono-agent-composer/references/feature-coverage.md

@@ -0,0 +1,80 @@
+# Feature Coverage
+
+Every framework capability and how a composed agent reaches it. Use this to answer "can the config do X?" without guessing: `config` = a `mono-agent.config.json` key (env var override always exists), `cli` = a `mono-agent` CLI flag/command, `auto` = always on when the app runs, `code` = programmatic escape hatch only, `dev` = development/test tooling. The repo's `docs/feature-registry.md` is the long-form source of truth.
+
+## Runtime
+
+| Capability | Coverage | Where |
+| --- | --- | --- |
+| Model backends: claude (sdk/cli), codex (cli), pi sdk providers (OpenAI, Copilot, OpenRouter, Ollama, ...) | config | `runtime.model` |
+| Backup models on retryable provider failure | config | `runtime.fallbackModels` |
+| Execution mode (sdk/cli), effort, max turns, workspace | config | `runtime.executionMode`, `runtime.effort`, `runtime.maxTurns`, `runtime.workspace` |
+| Tool-permission posture for CLI backends | config | `runtime.permissionMode` |
+| Reasoning summary verbosity | config | `runtime.reasoningSummary` |
+| Continuous provider sessions with idle eviction | config | `runtime.session.{mode,idleTimeoutMs}` |
+| Local providers (Ollama / LM Studio / OpenAI-compatible) | config | `providers.local[]` |
+| Pi OAuth credentials | config | `providers.piAuthPath` |
+| Context compaction, tool-output bloat guard, cost tracking | auto | built into every run |
+| Structured output (JSON schema), live input steering | code | harness `runtimeOptions` |
+| Tool approval gates (risk tiers, timeouts, always-allow) | code | `createMonoRuntime({ onToolApprovalRequest, ... })` — needs a host UI |
+| OpenAI Agents SDK backend / fully custom runtime | code | `startMonoAgentApp({ runtime })` |
+
+## Context, skills, memory
+
+| Capability | Coverage | Where |
+| --- | --- | --- |
+| Identity + optional soul documents | config | `context.identityPath`, `context.soulPath` |
+| Selected skills from a skills root | config | `context.skillsRoot`, `context.selectedSkills` |
+| Per-skill byte cap | config | `context.skillMaxBytes` |
+| Conversation history (in-memory, capped) | auto | sized from `runtime.maxTurns`; custom store via code |
+| Markdown memory (single-file / per-conversation, capped) | config | `memory.mode: "markdown"`, `path`, `maxBytes`, `scope` |
+| Journal memory (daily notes always in context) | config | `memory.mode: "journal"`, `path` |
+| Host summaries appended after runs | config | `memory.writeMode: "append-host-summary"` |
+| Entity graph + salience digest in context (journal) | config | automatic; path override `memory.graphPath` |
+| MCP recall tools (`memory_read_day`, `memory_list_days`, `memory_grep`, `memory_search`, `entity_get`) | config | `memory.tools.enabled` |
+| Model-initiated notes (`journal_append`) | config | `memory.tools.allowJournalAppend` |
+| Semantic `memory_search` (Ollama nomic-embed-text or OpenAI embeddings; keyword fallback when unset) | config | `memory.embeddings.{provider,model,endpoint,apiKey,apiKeyEnv}` |
+| Consolidation tools (`entity_upsert`, `memory_reindex`) | code | exposed by `@mono-agent/memory-mcp`, not in the default allowlist |
+
+## Tools, MCP, sandbox
+
+| Capability | Coverage | Where |
+| --- | --- | --- |
+| Fail-closed tool policy (empty allowlist = no tools) | auto | default |
+| Tool allow/deny lists (deny wins) | config | `tools.allowedTools`, `tools.disallowedTools` |
+| MCP servers (stdio/sse/http) from a JSON file | config | `tools.mcpConfigPath` |
+| Sandbox on/off + srt engine | config | `sandbox.mode` |
+| Network policy (none/localhost/allowlist/all) | config | `sandbox.network.{mode,allowlist}` |
+| Filesystem scopes (readable/writable roots, deny-write globs) | config | `sandbox.readableRoots`, `sandbox.writableRoots`, `sandbox.denyWrite` |
+| Fallback behavior when srt is unavailable | config | `sandbox.fallback`, `sandbox.unsafeAllowHostProcess` |
+| Request-scoped policies only tighten, never widen | auto | harness merge |
+
+## Channels
+
+| Capability | Coverage | Where |
+| --- | --- | --- |
+| Webhook (sync/async HTTP invoke + status polling) | config | `webhook` section |
+| OpenAI-compatible API (/v1/models, /v1/chat/completions, SSE, bearer) | config | `openaiApi` section |
+| Telegram (long polling, chat allowlist) | config | `telegram` section |
+| Slack (Socket Mode, channel allowlist, mention handling) | config | `slack` section |
+| WhatsApp (Baileys, QR login, group mention/any triggers) | config | `whatsapp` section |
+| A2A provider (Agent Card, JSON-RPC + REST, streaming, bearer) | config | `a2a.provider` + `a2a.agent` + `a2a.skill` |
+| A2A consumer settings (remote agent URLs, timeouts) | config + code | `a2a.consumer` holds settings; calls via `createA2AConsumerResponder` |
+| Cron jobs (five-field expressions, timezones, overlap skip) | config | `cron.jobs[]` |
+| Channel message texts / stream tuning (welcome, debounce, ...) | code | channel driver overrides |
+| Custom transports | code | implement `ChannelDriver`, pass via `startMonoAgentApp({ drivers })` |
+
+## Observability, operator surfaces, composition
+
+| Capability | Coverage | Where |
+| --- | --- | --- |
+| JSONL run artifacts (events + summaries, secrets redacted) | config | `artifacts.dir` |
+| Trace-source registry (heartbeat manifests for dashboards) | config | `traceability.{registryDir,sourceId,sourceLabel,heartbeatMs,staleAfterMs}` |
+| Operator console (browser settings editor, traceability views, live config re-apply, bearer token) | config + cli | `console.{enabled,port}`; `--port`, `--no-console` |
+| Terminal chat (TUI with transcript + redacted config pane) | cli | `mono-agent-tui --config ./mono-agent.config.json` |
+| Scaffold / validate / start / install-skill | cli | `mono-agent init|validate|start|install-skill` |
+| `.env` auto-loading | cli | automatic; `--env-file <path>` |
+| Explicit failure objects (no fake success) | auto | harness |
+| Per-request runtime options, custom memory/history stores | code | `createConfiguredAgentResponder` options |
+| Multi-agent delegation (`ask_collaborator` loopback MCP tool) | code | `@mono-agent/agent-orchestrator` |
+| Eval scenarios/suites (trajectory + judge assertions) | dev | `@mono-agent/agent-evals`, live runs via `MONO_AGENT_EVAL_LIVE=1` |

package/skills/mono-agent-composer/references/package-map.md

@@ -0,0 +1,136 @@
+# Package Composition Map
+
+Use this map to select the smallest mono-agent package set for a host. Package categories are logical ownership boundaries; the physical workspace layout stays flat under `packages/<package-name>`.
+
+## App Join (default)
+
+`@mono-agent/agent-app` is the config-first host: it loads `mono-agent.config.json`, builds the responder through `agent-host`, and drives every configured channel plus the operator console and traceability. It ships the `mono-agent` CLI (`init`, `validate`, `start`) and is the only publishable package allowed to compose communication adapters.
+
+```ts
+import { startMonoAgentApp } from "@mono-agent/agent-app";
+
+const app = await startMonoAgentApp({ cwd: process.cwd() });
+```
+
+Reach below it (the joins that follow) only when config cannot express the host.
+
+## Core Join
+
+Every real host needs these concepts:
+
+| Need | Package | Owns | Does not own |
+| --- | --- | --- | --- |
+| Shared request/response shape | `@mono-agent/agent-contracts` | `AgentResponder`, request, response, stream, cancellation contracts | Prompt building, runtime execution, transport |
+| Core config | `@mono-agent/config` | Runtime, context, memory, tools, artifact, traceability settings | Adapter credentials, chat allowlists |
+| Runtime facade | `@mono-agent/runtime-adapter` | Model refs, execution-mode validation, local provider runtime options | Prompts, adapters, memory |
+| Configured responder | `@mono-agent/agent-host` | Turns `MonoAgentConfig` into runtime, harness, and responder | Polling chats, serving APIs, adapter settings |
+
+Minimal local host:
+
+```ts
+import { loadMonoAgentConfigWithSources } from "@mono-agent/config";
+import { createConfiguredAgentResponder } from "@mono-agent/agent-host";
+
+const config = await loadMonoAgentConfigWithSources({
+  env: process.env,
+  cwd: process.cwd(),
+  jsonPath: "./mono-agent.config.json",
+});
+
+const responder = createConfiguredAgentResponder({ config });
+```
+
+## Context And Skill Join
+
+Use this path when the agent needs identity, selected skills, history, and optional memory:
+
+| Need | Package | Use |
+| --- | --- | --- |
+| Prompt assembly | `@mono-agent/context` | Load identity/SOUL/skills/history/memory into deterministic prompt context |
+| Selected skill bodies | `@mono-agent/skills` | Load only configured skills from `<skillsRoot>/<name>/SKILL.md` |
+| Markdown memory | `@mono-agent/memory-md` | Read capped memory blocks and optionally append host summaries |
+| Daily journal memory | `@mono-agent/memory-journal` | Keep a today note in context and persist continuous local journaling |
+| Entity graph memory | `@mono-agent/memory-graph` | Store local JSONL entities, relations, and observations (`memory.graphPath`) |
+| Searchable memory | `@mono-agent/memory-search` | Chunk and semantically search local memory with embeddings (`memory.embeddings`) |
+| Runtime memory tools | `@mono-agent/memory-mcp` | Expose memory tools over MCP when the runtime should query memory itself (`memory.tools`); also ships host-side `entity_upsert`/`memory_reindex` consolidation tools |
+
+Mono-agent selected skills are not auto-selected by description. The host chooses `context.selectedSkills`, and the harness loads those exact bodies.
+
+## Execution Join
+
+Use `@mono-agent/agent-harness` directly when a host needs custom runtime, memory, history, recorder, or request-scoped runtime options. Use `@mono-agent/agent-host` when config-driven composition is enough.
+
+`@mono-agent/agent-harness` owns:
+
+- loading identity/context files
+- loading selected skill bodies
+- reading memory blocks
+- invoking the runtime
+- recording run events and summaries
+- appending conversation history
+- optionally appending deterministic host summaries to memory
+- returning explicit failure objects instead of fake success
+
+## Tools And MCP Join
+
+Use `@mono-agent/tool-policy` for fail-closed tool/MCP policy normalization:
+
+```ts
+import { createToolPolicy, toolPolicyToRuntimeOptions } from "@mono-agent/tool-policy";
+
+const policy = createToolPolicy({
+  allowedTools: ["Read", "Grep"],
+  disallowedTools: ["WebFetch"],
+  mcpConfigPath: "./mcp.json",
+});
+
+const runtimeOptions = toolPolicyToRuntimeOptions(policy);
+```
+
+Do not grant broad tool access as a fallback. If the requested task needs tools, ask for the narrow allowlist or MCP config path.
+
+## Adapter Join
+
+Communication adapters are edge packages. They accept an `AgentResponder` and own only their transport-specific config and safety rules.
+
+| Surface | Package | First smoke |
+| --- | --- | --- |
+| Telegram | `@mono-agent/telegram-adapter` | Allowed chat sends a message |
+| Slack | `@mono-agent/slack-adapter` | Allowed channel or DM gets a streamed reply |
+| WhatsApp | `@mono-agent/whatsapp-adapter` | Allowed sender/group trigger produces a reply |
+| OpenAI-compatible API | `@mono-agent/openai-api-adapter` | `curl /v1/models` and `/v1/chat/completions` |
+| A2A provider/consumer | `@mono-agent/a2a-adapter` | Send text to the Agent Card URL |
+| Webhook | `@mono-agent/webhook-adapter` | `curl` the configured invocation path |
+| Cron | `@mono-agent/cron-adapter` | One scheduled or manually triggered invocation |
+
+Adapters must not import the harness, runtime adapter, memory packages, or other adapters. `@mono-agent/agent-app` composes them from config; custom hosts and demos may compose them directly.
+
+## Operator And Observability Join
+
+Use:
+
+- `@mono-agent/operator-console` for local browser settings and traceability (`console` config section; per-boot bearer token; saves re-apply live).
+- `@mono-agent/tui` for local terminal chat and redacted read-only config (`mono-agent-tui --config ./mono-agent.config.json`).
+- `@mono-agent/observability` for JSONL event artifacts, summaries, and trace-source registration.
+
+Traceability is local-first. A running host registers a source manifest; the operator console reads artifacts by `(sourceId, runId)` so duplicate run ids do not collide.
+
+## Evaluation Join
+
+Use `@mono-agent/agent-evals` to define end-to-end scenarios against a responder or harness: final-text assertions, trajectory/tool-call matching, cost/turn/duration budgets, and custom judges, with local JSON/markdown artifacts. Live-provider scenarios are skipped unless `MONO_AGENT_EVAL_LIVE=1`.
+
+## Multi-Agent Join
+
+Use `@mono-agent/agent-orchestrator` when one runtime should call named collaborator responders through a bounded MCP tool. Keep collaborator selection in the orchestrator layer, not inside A2A. A2A remains direct discovery and text/task communication.
+
+## Runtime Join
+
+Use `@mono-agent/runtime-adapter` unless the host has a custom runtime implementation that already satisfies `MonoRuntimeLike`.
+
+Supported model reference families:
+
+- `codex:<model>` with CLI execution
+- `claude:<model>` with SDK or CLI execution
+- `pi:<provider>:<model>` with SDK execution, including local providers such as Ollama
+
+Provider credentials belong in the provider/runtime environment, not in committed config.

package/skills/mono-agent-composer/references/validation.md

@@ -0,0 +1,94 @@
+# Validation
+
+Use validation that matches the chosen composition path. Do not claim the host works from a typecheck alone.
+
+## Config Validation (default path)
+
+In the user's agent folder:
+
+```bash
+mono-agent validate
+```
+
+The report covers core config, runtime support for the primary and every fallback model, identity/skills/memory/MCP paths, the sandbox policy, the operator console section, and every channel (`ok` / `waiting` / `off` / `error`). Exit 0 means the folder is ready to start. Fix every `[error]`; `[waiting]` channels are simply unconfigured.
+
+Then start and confirm the status lines:
+
+```bash
+mono-agent start
+```
+
+Every channel the user asked for must report `running` with its endpoint facts; anything `failed` is a blocker, not a footnote.
+
+## Documentation Validation
+
+To confirm a skills folder is indexable (replace `<skillsRoot>` with the
+agent's configured skills root, e.g. `./skills`):
+
+```bash
+node --input-type=module - <<'EOF'
+import { loadSkillIndexFromDirectory } from '@mono-agent/context';
+
+const skills = await loadSkillIndexFromDirectory('<skillsRoot>');
+console.log(JSON.stringify(skills, null, 2));
+EOF
+```
+
+Expected:
+
+- Every selected skill appears in the index.
+- The description is the first plain paragraph from its `SKILL.md`.
+- The `mainFile` points at `<skillsRoot>/<skill-name>/SKILL.md`.
+
+## Repo Validation
+
+Run the narrow checks for doc-only changes:
+
+```bash
+pnpm run check:architecture
+pnpm run typecheck
+git diff --check
+```
+
+If code or config behavior changes, add the relevant package tests:
+
+```bash
+pnpm --filter @mono-agent/<package> run test
+pnpm --filter @mono-agent/<package> run build
+pnpm --filter @mono-agent/<package> run typecheck
+```
+
+For broad host or demo changes, run the full workspace gate:
+
+```bash
+pnpm run build
+pnpm test
+pnpm run build:demo
+pnpm run typecheck:demo
+pnpm run test:demo
+```
+
+## Smoke Tests By Surface
+
+| Surface | Smoke |
+| --- | --- |
+| TUI | Start the host and complete one local prompt. |
+| Telegram | Send one allowed chat message and verify the reply. |
+| Slack | Send one allowed DM or channel message and verify formatting. |
+| WhatsApp | Send one allowed sender/group trigger and verify the reply. |
+| OpenAI API | `curl /v1/models` and `/v1/chat/completions`. |
+| A2A | Send text to the Agent Card URL with `sendA2AMessage()`. |
+| Webhook | `curl` the invocation path and inspect the response body/status. |
+| Cron | Run a one-off scheduled invocation or wait for one tick. |
+| Operator console | Open Settings and Traceability; confirm redaction and a visible run artifact. |
+| Journal memory tools | Ask the agent to recall yesterday (`memory_read_day`/`memory_grep` should appear in the run artifact). |
+| Semantic memory search | With `memory.embeddings` set (Ollama: `ollama pull nomic-embed-text` first), ask a paraphrased question about an old note and confirm `memory_search` returns it. |
+
+## Failure Handling
+
+Report failures as explicit blockers or follow-up work. Do not present:
+
+- a missing runtime as a successful fallback
+- disabled tools as a successful MCP integration
+- a fake adapter request as a product-runtime smoke
+- a redacted or skipped secret as proof that the live adapter works