@mono-agent/agent-app 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { isAppCoreConfigError, loadAppCoreConfig, MONO_AGENT_APP_FIELD_GROUPS, resolveAppArtifactDir, resolveAppTraceHeartbeatMs, resolveAppTraceRegistryDir, resolveAppTraceSourceId, resolveAppTraceSourceLabel, resolveAppTraceStaleAfterMs, } from "./app-config.js";
-export type { AppTraceDefaults, MonoAgentAppConfigInput } from "./app-config.js";
+export { consoleFieldGroup, isAppCoreConfigError, loadAppCoreConfig, MONO_AGENT_APP_FIELD_GROUPS, resolveAppArtifactDir, resolveAppConsoleSettings, resolveAppTraceHeartbeatMs, resolveAppTraceRegistryDir, resolveAppTraceSourceId, resolveAppTraceSourceLabel, resolveAppTraceStaleAfterMs, } from "./app-config.js";
+export type { AppConsoleSettings, AppTraceDefaults, MonoAgentAppConfigInput } from "./app-config.js";
 export { createA2AChannelDriver, createCronChannelDriver, createOpenAIApiChannelDriver, createSlackChannelDriver, createTelegramChannelDriver, createWebhookChannelDriver, createWhatsAppChannelDriver, defaultChannelDrivers, } from "./channels.js";
 export type { A2AChannelOverrides, ChannelDriver, ChannelDriverOverrides, ChannelId, ChannelStartInput, ChannelStatus, CronChannelOverrides, MonoAgentAppLogger, OpenAIApiChannelOverrides, RunningChannel, SlackChannelOverrides, TelegramChannelOverrides, TelegramPollerLike, WebhookChannelOverrides, WhatsAppChannelOverrides, } from "./channels.js";
 export { startMonoAgentApp } from "./app.js";
@@ -8,5 +8,7 @@ export { initMonoAgentFolder } from "./init.js";
 export type { InitMonoAgentFolderOptions, InitMonoAgentFolderResult } from "./init.js";
 export { validateMonoAgentFolder } from "./doctor.js";
 export type { ValidateMonoAgentFolderOptions, ValidationReport, ValidationSection, ValidationStatus, } from "./doctor.js";
-export { parseCliArgs, runCli } from "./cli.js";
+export { parseCliArgs, runCli, loadCliEnvFile } from "./cli.js";
+export { COMPOSER_SKILL_NAME, installComposerSkill } from "./install-skill.js";
+export type { InstallSkillOptions, InstallSkillResult, InstallSkillTarget } from "./install-skill.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,2BAA2B,EAC3B,qBAAqB,EACrB,0BAA0B,EAC1B,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EACV,YAAY,EACZ,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EACV,8BAA8B,EAC9B,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,2BAA2B,EAC3B,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACrG,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EACV,YAAY,EACZ,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EACV,8BAA8B,EAC9B,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,7 +1,8 @@
-export { isAppCoreConfigError, loadAppCoreConfig, MONO_AGENT_APP_FIELD_GROUPS, resolveAppArtifactDir, resolveAppTraceHeartbeatMs, resolveAppTraceRegistryDir, resolveAppTraceSourceId, resolveAppTraceSourceLabel, resolveAppTraceStaleAfterMs, } from "./app-config.js";
+export { consoleFieldGroup, isAppCoreConfigError, loadAppCoreConfig, MONO_AGENT_APP_FIELD_GROUPS, resolveAppArtifactDir, resolveAppConsoleSettings, resolveAppTraceHeartbeatMs, resolveAppTraceRegistryDir, resolveAppTraceSourceId, resolveAppTraceSourceLabel, resolveAppTraceStaleAfterMs, } from "./app-config.js";
 export { createA2AChannelDriver, createCronChannelDriver, createOpenAIApiChannelDriver, createSlackChannelDriver, createTelegramChannelDriver, createWebhookChannelDriver, createWhatsAppChannelDriver, defaultChannelDrivers, } from "./channels.js";
 export { startMonoAgentApp } from "./app.js";
 export { initMonoAgentFolder } from "./init.js";
 export { validateMonoAgentFolder } from "./doctor.js";
-export { parseCliArgs, runCli } from "./cli.js";
+export { parseCliArgs, runCli, loadCliEnvFile } from "./cli.js";
+export { COMPOSER_SKILL_NAME, installComposerSkill } from "./install-skill.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,2BAA2B,EAC3B,qBAAqB,EACrB,0BAA0B,EAC1B,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAkBvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAO7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAOtD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,2BAA2B,EAC3B,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAkBvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAO7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAOtD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/install-skill.d.ts

@@ -0,0 +1,21 @@
+export type InstallSkillTarget = "claude" | "codex" | "both";
+export interface InstallSkillOptions {
+    readonly target: InstallSkillTarget;
+    /** Overwrite an existing installed copy instead of refusing. */
+    readonly force: boolean;
+    /** Test injection; defaults to os.homedir(). */
+    readonly homeDir?: string;
+    /** Test injection; defaults to the skill bundled with this package. */
+    readonly sourceDir?: string;
+}
+export interface InstallSkillResult {
+    readonly installed: readonly string[];
+}
+export declare const COMPOSER_SKILL_NAME = "mono-agent-composer";
+/**
+ * Copies the bundled mono-agent-composer skill into the harness skill folders
+ * (~/.claude/skills and/or ~/.codex/skills) so Claude Code and Codex can use
+ * it to compose new agents.
+ */
+export declare function installComposerSkill(options: InstallSkillOptions): Promise<InstallSkillResult>;
+//# sourceMappingURL=install-skill.d.ts.map

package/dist/install-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-skill.d.ts","sourceRoot":"","sources":["../src/install-skill.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAWzD;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsBpG"}

package/dist/install-skill.js

@@ -0,0 +1,52 @@
+import { cp, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const COMPOSER_SKILL_NAME = "mono-agent-composer";
+// dist/install-skill.js and src/install-skill.ts both sit one level below the
+// package root, so ../skills resolves to the bundled skills folder either way.
+const BUNDLED_SKILL_DIR = fileURLToPath(new URL(`../skills/${COMPOSER_SKILL_NAME}`, import.meta.url));
+const TARGET_HARNESS_DIRS = {
+    claude: ".claude",
+    codex: ".codex",
+};
+/**
+ * Copies the bundled mono-agent-composer skill into the harness skill folders
+ * (~/.claude/skills and/or ~/.codex/skills) so Claude Code and Codex can use
+ * it to compose new agents.
+ */
+export async function installComposerSkill(options) {
+    const sourceDir = options.sourceDir ?? BUNDLED_SKILL_DIR;
+    await assertSkillSource(sourceDir);
+    const home = options.homeDir ?? homedir();
+    const targets = options.target === "both" ? ["claude", "codex"] : [options.target];
+    const destinations = targets.map((target) => join(home, TARGET_HARNESS_DIRS[target], "skills", COMPOSER_SKILL_NAME));
+    if (!options.force) {
+        for (const destination of destinations) {
+            if (await pathExists(destination)) {
+                throw new Error(`Destination ${destination} already exists. Re-run with --force to overwrite.`);
+            }
+        }
+    }
+    const installed = [];
+    for (const destination of destinations) {
+        await cp(sourceDir, destination, { recursive: true, force: true });
+        installed.push(destination);
+    }
+    return { installed };
+}
+async function assertSkillSource(sourceDir) {
+    if (!(await pathExists(join(sourceDir, "SKILL.md")))) {
+        throw new Error(`Bundled skill is missing SKILL.md at ${sourceDir}; the package looks broken.`);
+    }
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=install-skill.js.map

package/dist/install-skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-skill.js","sourceRoot":"","sources":["../src/install-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAkBzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAEzD,8EAA8E;AAC9E,+EAA+E;AAC/E,MAAM,iBAAiB,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,aAAa,mBAAmB,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAEtG,MAAM,mBAAmB,GAAkE;IACzF,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,QAAQ;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAA4B;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,iBAAiB,CAAC;IACzD,MAAM,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAEnC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC;IAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,OAAO,CAAW,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,MAAM,CAAW,CAAC;IACzG,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAErH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACvC,IAAI,MAAM,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,eAAe,WAAW,oDAAoD,CAAC,CAAC;YAClG,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,MAAM,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,SAAiB;IAChD,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,wCAAwC,SAAS,6BAA6B,CAAC,CAAC;IAClG,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-app",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Config-first mono-agent host: builds a responder and starts every configured communication channel, operator console, and traceability from one mono-agent.config.json.",
   "type": "module",
   "license": "UNLICENSED",
@@ -18,23 +18,24 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "dependencies": {
-    "@mono-agent/a2a-adapter": "0.1.0",
-    "@mono-agent/agent-contracts": "0.1.0",
-    "@mono-agent/agent-host": "0.1.0",
-    "@mono-agent/config": "0.1.0",
-    "@mono-agent/cron-adapter": "0.1.0",
-    "@mono-agent/observability": "0.1.0",
-    "@mono-agent/openai-api-adapter": "0.1.0",
-    "@mono-agent/operator-console": "0.1.0",
-    "@mono-agent/runtime-adapter": "0.1.0",
-    "@mono-agent/settings": "0.1.0",
-    "@mono-agent/slack-adapter": "0.1.0",
-    "@mono-agent/telegram-adapter": "0.1.0",
-    "@mono-agent/webhook-adapter": "0.1.0",
-    "@mono-agent/whatsapp-adapter": "0.1.0"
+    "@mono-agent/a2a-adapter": "0.2.0",
+    "@mono-agent/agent-contracts": "0.2.0",
+    "@mono-agent/agent-host": "0.2.0",
+    "@mono-agent/config": "0.2.0",
+    "@mono-agent/cron-adapter": "0.2.0",
+    "@mono-agent/observability": "0.2.0",
+    "@mono-agent/openai-api-adapter": "0.2.0",
+    "@mono-agent/operator-console": "0.2.0",
+    "@mono-agent/runtime-adapter": "0.2.0",
+    "@mono-agent/settings": "0.2.0",
+    "@mono-agent/slack-adapter": "0.2.0",
+    "@mono-agent/telegram-adapter": "0.2.0",
+    "@mono-agent/webhook-adapter": "0.2.0",
+    "@mono-agent/whatsapp-adapter": "0.2.0"
   },
   "publishConfig": {
     "access": "public"

package/skills/mono-agent-composer/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: mono-agent-composer
+description: Construct a working mono-agent in the current folder from one mono-agent.config.json — discover the desired runtime (with backup models), channels, skills, MCP servers, memory strategy, and sandbox, then init, validate, and start it with the mono-agent CLI. Use when a user wants to build, configure, or troubleshoot an agent built from @mono-agent packages.
+---
+
+# Mono Agent Composer
+
+Construct a working mono-agent in the user's current folder — empty or already holding knowledge — from one `mono-agent.config.json`. Discover what the user wants (runtime with backup models, communication channels incl. crons and webhooks, skills, MCP servers, memory strategy incl. semantic search, sandbox, operator console, observability), write the config, then make it run with the `mono-agent` CLI. No hand-written host code unless the user genuinely needs programmatic composition. `references/feature-coverage.md` maps every framework feature to a config key, CLI flag, or the programmatic escape hatch — consult it before declaring anything impossible or inventing keys.
+
+## Operating Rules
+
+- The deliverable is a folder that works: `mono-agent.config.json` + `IDENTITY.md` (+ optional `skills/`, `mcp.json`), validated and started — not a tutorial.
+- Start by discovering the intended agent product, not by naming packages.
+- Ask one question at a time; skip anything the user already answered.
+- Respect existing knowledge: if the folder has `AGENTS.md`, `CLAUDE.md`, `README.md`, or an existing `IDENTITY.md`, reference it from the identity instead of replacing it. Never overwrite existing files.
+- Fail closed: no allowed tools, no memory writes, loopback-only network until the user opts in.
+- Do not fake runtime success, silently broaden tool access, or hide provider/MCP failures. Backup models are configured failover (`runtime.fallbackModels`), never silent substitution.
+- Secrets stay in env vars or the untracked config file; never commit tokens or `.env*` files.
+
+## Prerequisites
+
+The `mono-agent` CLI ships with `@mono-agent/agent-app` on npm:
+
+```bash
+npm install -g @mono-agent/agent-app   # or: npx @mono-agent/agent-app …
+```
+
+To run an unreleased build instead, use a clone of the mono-agent workspace:
+
+```bash
+git clone <mono-agent-repo> ~/mono-agent && cd ~/mono-agent
+corepack enable && pnpm install --frozen-lockfile && pnpm run build
+alias mono-agent="node ~/mono-agent/packages/agent-app/dist/cli.js"
+```
+
+Everything below runs in the user's agent folder, not the workspace.
+
+## Composition Flow
+
+1. **Discover.** Read `references/discovery-questions.md` and resolve: runtime model + backup models, channels, identity/knowledge, skills, tools/MCP, memory strategy, sandbox, observability, and the acceptance smoke test.
+2. **Scaffold.** In the user's folder run:
+
+   ```bash
+   mono-agent init --model <ref> [--fallback-models <csv>] [--memory markdown|journal]
+   ```
+
+   This writes a minimal `mono-agent.config.json` (webhook enabled as the zero-credential smoke channel), an `IDENTITY.md` that references any knowledge files already present, and `.mono-agent/` working directories. It never overwrites existing files.
+3. **Configure.** Edit `mono-agent.config.json` to match the discovery answers. Read `references/config-blueprint.md` for the full annotated config shape: every channel section, skills, MCP, memory, sandbox, and fallback models.
+4. **Validate.**
+
+   ```bash
+   mono-agent validate
+   ```
+
+   Fix every `[error]` section. `[waiting]` channels are fine — they are simply not configured yet. Re-run until the report says the config is ready.
+5. **Start and smoke.**
+
+   ```bash
+   mono-agent start
+   ```
+
+   Then run the acceptance smoke test matching the chosen channel (see `references/validation.md`). The operator console URL printed at start lets the user edit config in the browser; saves re-apply live.
+
+## When Config Is Not Enough
+
+Config-first covers one responder served over any combination of the seven channels (webhook, OpenAI-compatible API, Telegram, Slack, WhatsApp, A2A, cron) plus the operator console, sandbox, memory (markdown or journal with entity graph and optional semantic search), and traceability. Drop to programmatic composition only for: custom runtimes (`MonoRuntimeLike`, incl. the OpenAI Agents SDK), request-scoped runtime extensions, tool approval gates, structured output schemas, multi-agent orchestration (`@mono-agent/agent-orchestrator`), custom channel message texts, or bespoke transports — `references/feature-coverage.md` lists which features are config keys and which are code-only. Read `references/package-map.md` for the package boundaries, and start from `startMonoAgentApp({ drivers, runtime, ... })` or `@mono-agent/agent-host` rather than re-writing lifecycle glue. For eval suites over the composed agent, use `@mono-agent/agent-evals`.
+
+## Implementation References
+
+- `references/discovery-questions.md` — the question sequence and which config keys each answer fills.
+- `references/config-blueprint.md` — annotated `mono-agent.config.json` covering every section, plus the folder layout and programmatic escape hatch.
+- `references/feature-coverage.md` — every framework feature mapped to config / CLI / code / dev-tooling coverage; the answer to "can the config do X?".
+- `references/package-map.md` — which package owns what, for programmatic composition and troubleshooting.
+- `references/validation.md` — validation commands and per-channel smoke tests; read before claiming the agent works.
+
+## Done Criteria
+
+- `mono-agent validate` exits 0 in the user's folder.
+- `mono-agent start` runs, and the chosen channel's smoke test passed with a real response from the configured runtime.
+- The config file matches what the user asked for: model + backups, channels, skills, MCP, memory, sandbox.
+- Existing knowledge files are referenced, not duplicated or overwritten.
+- No secrets are committed.

package/skills/mono-agent-composer/references/config-blueprint.md

@@ -0,0 +1,233 @@
+# Config Blueprint
+
+One `mono-agent.config.json` declares the whole agent. Paths are relative to the folder; every field also has a `MONO_AGENT_*` env var that overrides it (env > JSON > defaults). Omit a section to leave that capability off — every section except `runtime.model` and `context.identityPath` is optional. `references/feature-coverage.md` maps every framework feature to its config key; if a capability is not listed there, it needs the programmatic escape hatch.
+
+## Folder Layout
+
+```text
+my-agent/
+  mono-agent.config.json   # the single declaration below
+  IDENTITY.md              # role, boundaries, references to existing knowledge
+  skills/                  # optional: <skill-name>/SKILL.md per selected skill
+  mcp.json                 # optional: MCP server definitions
+  .env                     # optional: secrets; auto-loaded by the CLI, never committed
+  .mono-agent/
+    artifacts/             # JSONL run summaries + events
+    workspace/             # runtime working directory (if not ".")
+    memory/                # journal memory root (daily notes, graph.jsonl, index/)
+    whatsapp-auth/         # Baileys auth state (WhatsApp channel only)
+    trace-sources/         # traceability registry (if kept folder-local)
+```
+
+## Annotated Config
+
+```jsonc
+{
+  // Runtime: primary model plus ordered backups tried on retryable provider
+  // failures (failover is reported in run results, never silent).
+  "runtime": {
+    "model": "claude:claude-sonnet-4-6",   // claude:* | codex:* | pi:<provider>:<model>
+    "fallbackModels": ["pi:ollama:gemma4:31b"],
+    "executionMode": "sdk",                // sdk | cli (default inferred from model)
+    "effort": "medium",                    // none|low|medium|high|xhigh|max
+    "permissionMode": "default",           // default|plan|acceptEdits|bypassPermissions (CLI backends)
+    "reasoningSummary": "auto",            // auto|concise|detailed|off|on
+    "maxTurns": 8,                         // 1-100
+    "workspace": ".",
+    "session": { "mode": "continuous", "idleTimeoutMs": 1800000 } // or "per-message"
+  },
+
+  // Local/self-hosted providers for pi:<provider>:<model> references.
+  "providers": {
+    "piAuthPath": "~/.pi/agent/auth.json", // Pi OAuth credentials (openai-codex, ...)
+    "local": [
+      {
+        "id": "ollama",
+        "type": "ollama",                  // ollama | lmstudio | openai_compat
+        "baseUrl": "http://localhost:11434",
+        "enabled": true,
+        "trustPublicUrl": false,           // explicit opt-in for non-private URLs
+        "apiKeyEnv": "MY_PROVIDER_KEY",    // or inline "apiKey" (untracked file only)
+        "models": [{ "name": "gemma4:31b", "capabilities": { "context_window": 32768 } }]
+      }
+    ]
+  },
+
+  // Identity, optional soul, and selected skills.
+  "context": {
+    "identityPath": "./IDENTITY.md",
+    "soulPath": "./SOUL.md",
+    "skillsRoot": "./skills",
+    "selectedSkills": ["research"],        // exact names; no auto-selection
+    "skillMaxBytes": 48000                 // per-skill byte cap (256-1,000,000)
+  },
+
+  // Memory strategy. Omit the section for no memory.
+  "memory": {
+    "mode": "journal",                     // markdown | journal
+    "path": "./.mono-agent/memory",        // file for markdown, root dir for journal
+    "writeMode": "append-host-summary",    // disabled | append-host-summary
+    "scope": "single-file",                // markdown only: single-file | per-conversation
+    "maxBytes": 64000,
+    "tools": { "enabled": true, "allowJournalAppend": true }, // journal only: MCP recall tools
+    "graphPath": "./.mono-agent/memory/graph.jsonl",          // journal only; this is the default
+    "embeddings": {                        // optional: semantic memory_search
+      "provider": "ollama",                // ollama | openai
+      "model": "nomic-embed-text",         // default per provider
+      "endpoint": "http://localhost:11434",
+      "apiKeyEnv": "OPENAI_API_KEY"        // or inline "apiKey"; required for openai
+    }
+  },
+
+  // Fail-closed tool policy + MCP servers. Deny wins; overlap is rejected.
+  "tools": {
+    "allowedTools": ["Read", "Grep"],      // built-ins: Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch
+    "disallowedTools": ["Bash"],
+    "mcpConfigPath": "./mcp.json"          // stdio/sse/http servers; inlined for SDK runtimes
+  },
+
+  // Sandbox for runtime commands. Omit for no sandboxing.
+  "sandbox": {
+    "mode": "native",                      // native (srt-wrapped) | off
+    "network": { "mode": "none", "allowlist": [] }, // none|localhost|allowlist|all; *.suffix wildcards
+    "readableRoots": ["."],                // relative entries resolve against the workspace
+    "writableRoots": ["."],
+    "denyWrite": [".env", ".env.*", ".git/config", ".git/hooks/**"], // these are the defaults
+    "fallback": "fail-closed",             // fail-closed | unsafe-host-process
+    "unsafeAllowHostProcess": false        // explicit opt-in required for the unsafe fallback
+  },
+
+  // Observability: JSONL artifacts + the trace-source registry dashboards read.
+  "artifacts": { "dir": "./.mono-agent/artifacts" },
+  "traceability": {
+    "registryDir": "./.mono-agent/trace-sources",
+    "sourceId": "my-agent",
+    "sourceLabel": "My Agent",
+    "heartbeatMs": 10000,
+    "staleAfterMs": 30000
+  },
+
+  // Local operator console (browser settings + traceability). On by default.
+  "console": {
+    "enabled": true,
+    "port": 0                              // 0 or omitted picks a free loopback port
+  },
+
+  // ----- Channels: one section per channel; all independent. An unconfigured
+  // ----- channel reports waiting_for_config and never blocks the others.
+
+  "webhook": {
+    "enabled": true,
+    "host": "127.0.0.1",                   // loopback-only unless allowNonLoopback
+    "port": 0,                             // 0 picks a free port
+    "path": "/webhook/invoke",
+    "allowNonLoopback": false,
+    "defaultMode": "sync",                 // sync | async (202 + status URL polling)
+    "retentionMs": 300000,                 // async status retention
+    "maxStoredRequests": 100
+  },
+
+  "openaiApi": {
+    "enabled": true,
+    "host": "127.0.0.1",
+    "port": 4040,
+    "basePath": "/v1",                     // serves /v1/models + /v1/chat/completions (SSE)
+    "allowNonLoopback": false,
+    "modelId": "my-agent",                 // model id advertised to API clients
+    "apiKey": "..."                        // optional bearer required from clients
+  },
+
+  "telegram": {
+    "botToken": "...",
+    "allowedChatIds": ["123456789"],       // or "allowAllChats": true
+    "allowAllChats": false
+  },
+
+  "slack": {
+    "botToken": "xoxb-...",                // Socket Mode app
+    "appToken": "xapp-...",
+    "allowedChannelIds": ["C0123"],        // or "allowAllChannels": true
+    "allowAllChannels": false,
+    "botUserIds": ["U0BOT"],               // mention detection
+    "mentionTextAliases": ["@agent"],
+    "stripMentionText": true
+  },
+
+  "whatsapp": {
+    "allowedChatJids": ["123@s.whatsapp.net"], // or "allowAllChats": true
+    "allowAllChats": false,
+    "groupMode": "mention",                // mention | any (group trigger rule)
+    "botJids": ["456@s.whatsapp.net"],
+    "mentionTextAliases": ["@agent"],
+    "stripMentionText": true
+    // Baileys auth state lives in .mono-agent/whatsapp-auth; the start log
+    // prints a QR code to scan on first login.
+  },
+
+  "a2a": {
+    "provider": {
+      "enabled": true,
+      "host": "127.0.0.1",
+      "port": 4201,
+      "publicBaseUrl": "https://agent.example.com", // Agent Card URL when fronted by a proxy
+      "allowNonLoopback": false,
+      "requireBearer": false,
+      "bearerToken": "..."
+    },
+    "agent": { "name": "My Agent", "description": "What it does.", "version": "0.1.0" },
+    "skill": { "id": "main", "name": "Main", "description": "Primary skill.", "tags": ["agent"] },
+    "consumer": {                          // settings for calling remote A2A agents
+      "remoteAgentUrls": ["http://127.0.0.1:4202"],
+      "defaultRemoteAgentUrl": "http://127.0.0.1:4202",
+      "bearerToken": "...",
+      "timeoutMs": 30000
+      // Consumed programmatically (createA2AConsumerResponder); the app's A2A
+      // channel runs the provider side.
+    }
+  },
+
+  "cron": {
+    "jobs": [
+      {
+        "id": "daily",
+        "enabled": true,
+        "expression": "0 9 * * *",         // five-field cron
+        "timezone": "UTC",                 // IANA timezone
+        "prompt": "Post the morning summary.",
+        "conversationId": "cron-daily"     // optional: share memory/history across ticks
+      }
+    ]
+    // Overlapping ticks of the same job are skipped, never queued.
+  }
+}
+```
+
+## Lifecycle
+
+```bash
+mono-agent init --model claude:claude-sonnet-4-6 --fallback-models pi:ollama:gemma4:31b [--memory markdown|journal]
+mono-agent validate     # per-section report incl. sandbox, console, every channel; exit 0 means ready
+mono-agent start        # console + traceability + every configured channel
+mono-agent start --no-console   # headless (or "console": { "enabled": false })
+mono-agent start --port 4400    # fixed console port (or "console": { "port": 4400 })
+```
+
+A `.env` file in the folder is loaded automatically (exported shell variables win); use `--env-file <path>` for an alternate file. `start` prints the operator console URL (config editing in the browser; saves re-apply live without restarting), the traceability source, and one status line per channel: `running` with its endpoint facts, `waiting_for_config` with the exact missing setting, `disabled`, or `failed` with the reason.
+
+For a local terminal chat against the same config, `@mono-agent/tui` ships a `mono-agent-tui` bin: `mono-agent-tui --config ./mono-agent.config.json`.
+
+## Programmatic Escape Hatch
+
+When config cannot express the host (custom runtime, request-scoped runtime extensions, custom channels, tool approval gates, structured output schemas), compose on the same package the CLI uses:
+
+```ts
+import { startMonoAgentApp, defaultChannelDrivers } from "@mono-agent/agent-app";
+
+const app = await startMonoAgentApp({
+  cwd: process.cwd(),
+  runtime: myCustomRuntime,            // any MonoRuntimeLike (incl. createOpenAIAgentsRuntime)
+  drivers: [...defaultChannelDrivers(), myCustomDriver],
+});
+```
+
+For a bare responder without channels, use `@mono-agent/config` + `@mono-agent/agent-host` (`createConfiguredAgentResponder` — also takes `memory`, `historyStore`, `runtimeOptions`, `runtimeOptionsForRequest`). For multi-agent orchestration, add `@mono-agent/agent-orchestrator` (`createCollaboratorToolRuntimeExtension`) — see `references/package-map.md`. Channel message texts and stream tuning (welcome/help/error texts, edit debounce) are channel-driver overrides, not config keys.

package/skills/mono-agent-composer/references/discovery-questions.md

@@ -0,0 +1,137 @@
+# Discovery Questions
+
+Use this sequence to fill `mono-agent.config.json` before running anything. Ask one question at a time. Skip questions whose answer is already explicit in the user's request. Each answer maps to concrete config keys.
+
+## 1. Runtime And Backup Models
+
+Question:
+
+```text
+Which model should drive the agent, and should any backups take over when the provider fails?
+
+1. `claude:<model>` through SDK or CLI mode
+2. `codex:<model>` through CLI mode
+3. `pi:<provider>:<model>` through SDK mode (OpenAI, Copilot, OpenRouter, local Ollama, ...)
+4. A custom MonoRuntimeLike supplied programmatically (escape hatch)
+```
+
+Fills: `runtime.model`, `runtime.fallbackModels` (ordered backup references tried on retryable provider failures), `runtime.executionMode` (usually inferred), `runtime.effort`, `runtime.maxTurns`.
+
+For local models also fill `providers.local` (e.g. an Ollama base URL plus model capabilities). Follow-up only if needed: continuous provider session per conversation (`runtime.session.mode: "continuous"`, default) versus stateless per-message.
+
+## 2. Channels Of Communication
+
+Question:
+
+```text
+Where should people (or other agents) reach this agent? Pick every channel that applies:
+
+1. Webhook (HTTP POST, zero credentials — good first smoke test)
+2. OpenAI-compatible API (OpenWebUI and other API clients)
+3. Telegram
+4. Slack
+5. WhatsApp
+6. A2A (agent-to-agent provider/consumer)
+7. Cron (scheduled prompts, no inbound channel)
+```
+
+Fills one config section per choice: `webhook`, `openaiApi`, `telegram`, `slack`, `whatsapp`, `a2a`, `cron`. Channels are independent: an unconfigured channel reports `waiting_for_config` and never blocks the others. For chat channels collect tokens and allowlists (chat IDs, channel IDs, JIDs). For HTTP channels collect host/port/path and whether non-loopback binding is allowed (default: loopback only).
+
+## 3. Identity And Existing Knowledge
+
+Question:
+
+```text
+What is this agent's role, and does this folder already contain knowledge it must respect?
+```
+
+Fills: `context.identityPath` (default `./IDENTITY.md`), optional `context.soulPath`, `runtime.workspace`. `mono-agent init` detects `AGENTS.md`, `CLAUDE.md`, `README.md`, and `SOUL.md` and references them from the generated identity — keep those references rather than copying content.
+
+## 4. Skills
+
+Question:
+
+```text
+Should this agent load selected skills?
+
+1. Yes, from a `skills/` directory in this folder
+2. Yes, from an external skills directory
+3. No selected skills for the first pass
+```
+
+Fills: `context.skillsRoot`, `context.selectedSkills`, optionally `context.skillMaxBytes` (per-skill byte cap, default 48000). Skill discovery loads immediate child directories only: `<skillsRoot>/<skill-name>/SKILL.md`. Skill files may carry YAML frontmatter (Claude Code style); the description is the first prose paragraph after it.
+
+## 5. Tools And MCP Servers
+
+Question:
+
+```text
+What tools or MCP servers does the agent actually need?
+
+1. No tools yet; fail closed (recommended)
+2. A small allowlist of built-in tools
+3. MCP servers from an mcp.json config file
+4. Both
+```
+
+Fills: `tools.allowedTools`, `tools.disallowedTools` (denylist wins), `tools.mcpConfigPath`. Record exact tool names; do not broaden access as a convenience.
+
+## 6. Memory Strategy
+
+Question:
+
+```text
+Should the agent remember anything between conversations?
+
+1. No durable memory yet (recommended for first integration)
+2. Markdown memory file (read into context; optional host summaries appended)
+3. Journal memory (daily notes + entity graph, optional MCP recall tools)
+4. Journal memory with semantic search (adds an embedding index for memory_search)
+```
+
+Fills: the `memory` section — `mode` (`markdown`/`journal`), `path`, `writeMode` (`disabled`/`append-host-summary`), `scope`, and for journal mode `tools.enabled` / `tools.allowJournalAppend` to give the runtime memory recall/append tools over MCP. The entity graph defaults to `<path>/graph.jsonl` (`memory.graphPath` to relocate). For semantic search fill `memory.embeddings`: `provider` (`ollama` with local `nomic-embed-text` — pull it first with `ollama pull nomic-embed-text` — or `openai` which requires `apiKey`/`apiKeyEnv`), optional `model`/`endpoint`. Without embeddings, `memory_search` falls back to keyword search.
+
+## 7. Sandbox
+
+Question:
+
+```text
+Should runtime commands run inside a sandbox?
+
+1. No sandbox for the first pass
+2. Native sandbox, no network (fail closed)
+3. Native sandbox with localhost or an explicit network allowlist
+4. Native sandbox with custom filesystem scopes (extra readable/writable roots)
+```
+
+Fills: the `sandbox` section — `mode`, `network.mode` (`none`/`localhost`/`allowlist`/`all`), `network.allowlist`, `readableRoots`/`writableRoots` (relative entries resolve against the workspace; default: workspace only), `denyWrite` glob patterns (defaults already deny `.env*`, `.git/config`, `.git/hooks/**`), `fallback` (`fail-closed` recommended; `unsafe-host-process` only with explicit consent plus `unsafeAllowHostProcess: true`).
+
+## 8. Observability
+
+Question:
+
+```text
+Do you need browsable traceability or just local artifacts?
+
+1. JSONL artifacts and the operator console (recommended; console is on by default)
+2. JSONL artifacts and the console on a fixed port
+3. JSONL artifacts only (headless)
+```
+
+Fills: `artifacts.dir`, `traceability.registryDir` / `sourceId` / `sourceLabel`, and the `console` section — `console.port` for a fixed loopback port, `console.enabled: false` (or `start --no-console`) for headless. Artifacts record runtime/tool/message events and summaries, not private chain-of-thought. For a local terminal chat instead of (or alongside) the browser console, mention `mono-agent-tui --config ./mono-agent.config.json`.
+
+## 9. Acceptance Smoke Test
+
+Question:
+
+```text
+What proves this agent works?
+
+1. A curl POST to the webhook invoke URL
+2. A curl to /v1/models and /v1/chat/completions
+3. A Telegram/Slack/WhatsApp message from an allowed sender
+4. An A2A message to the Agent Card URL
+5. A cron tick
+```
+
+The answer decides which smoke from `references/validation.md` must pass before the work is done.