@rubytech/create-maxy-code 0.1.244 → 0.1.246

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.244",
+  "version": "0.1.246",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/docs/superpowers/plans/2026-06-04-public-agent-knowledge-delivery.md

@@ -0,0 +1,230 @@
+# Public Agent Knowledge Delivery — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the public agent's `KNOWLEDGE.md` reach its spawn prompt, refuse a dud (empty/missing SOUL or KNOWLEDGE) public spawn with a distinct logged reason, and stop seeding/reading the dead public `SOUL`/`config` templates and `plugins` config field.
+
+**Architecture:** The only spawn-prompt path is `composeAppendSystemPrompt` in `claude-session-manager`. It reads `agents/<role>/{IDENTITY,SOUL}.md`; we add a public-only `KNOWLEDGE.md` read rendered as `<knowledge>` after `<soul>`, with strict empty/missing refusal. `pty-spawner` maps the new refusal reasons and emits the per-spawn byte-count line. The installer stops manufacturing a public agent on fresh install but re-syncs the Rubytech IDENTITY into existing agent dirs on upgrade. The UI config reader drops the unused `plugins` field. The admin skill doc is corrected to match.
+
+**Tech Stack:** TypeScript (Node, vitest), bash (`setup-account.sh`), markdown (SKILL.md).
+
+---
+
+### Task 1: `system-prompt.ts` — read KNOWLEDGE for public, distinct refusal reasons
+
+**Files:**
+- Modify: `services/claude-session-manager/src/system-prompt.ts`
+- Test: `services/claude-session-manager/src/__tests__/system-prompt.test.ts`
+
+**Behaviours:**
+- `AppendBlockResult` ok:true gains `knowledgeBytes: number`.
+- `AppendBlockResult` ok:false `reason` union gains `'soul-empty' | 'knowledge-missing' | 'knowledge-empty'`.
+- `renderAppendBlock` gains a `knowledgeContent: string | null` param; when non-null, render `<knowledge>\n{content}\n</knowledge>` immediately after `</soul>`, before `<about-owner>`; return `knowledgeBytes`. Null ⇒ no block, no bytes (admin + self-test + drift unchanged).
+- `composeAppendSystemPrompt`: IDENTITY failure → `identity-unresolved` (all roles, unchanged). SOUL failure → `identity-unresolved` for admin (unchanged); for `role==='public'` → `soul-empty`. When `role==='public'`, read `<roleDir>/KNOWLEDGE.md` via `readIdentityFile`: detail ending `:empty` → `knowledge-empty`; any other failure (ENOENT/unreadable) → `knowledge-missing`. Pass content to `renderAppendBlock`; admin passes `null`.
+
+- [ ] **Step 1: Write failing tests** — append to `system-prompt.test.ts`:
+
+```ts
+describe('composeAppendSystemPrompt — public KNOWLEDGE delivery', () => {
+  function makePublic(seed: { identity?: string | null; soul?: string | null; knowledge?: string | null }): string {
+    const dir = mkdtempSync(join(tmpdir(), 'task618-account-'))
+    const roleDir = join(dir, 'agents', 'public')
+    mkdirSync(roleDir, { recursive: true })
+    if (typeof seed.identity === 'string') writeFileSync(join(roleDir, 'IDENTITY.md'), seed.identity)
+    if (typeof seed.soul === 'string') writeFileSync(join(roleDir, 'SOUL.md'), seed.soul)
+    if (typeof seed.knowledge === 'string') writeFileSync(join(roleDir, 'KNOWLEDGE.md'), seed.knowledge)
+    return dir
+  }
+
+  it('public + non-empty KNOWLEDGE ⇒ <knowledge> verbatim, ordered after <soul>, knowledgeBytes>0', () => {
+    const knowledge = '# Knowledge\nWe open 9-5. Sale price £450k.\n'
+    const accountDir = makePublic({ identity: 'I', soul: 'S', knowledge })
+    try {
+      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
+      expect(result.ok).toBe(true)
+      if (!result.ok) return
+      expect(result.block).toContain(`<knowledge>\n${knowledge}\n</knowledge>`)
+      expect(result.block.indexOf('<knowledge>')).toBeGreaterThan(result.block.indexOf('</soul>'))
+      expect(result.knowledgeBytes).toBe(Buffer.byteLength(knowledge, 'utf8'))
+    } finally { rmSync(accountDir, { recursive: true, force: true }) }
+  })
+
+  it('public + missing KNOWLEDGE ⇒ ok:false reason=knowledge-missing', () => {
+    const accountDir = makePublic({ identity: 'I', soul: 'S' })
+    try {
+      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
+      expect(result.ok).toBe(false)
+      if (result.ok) return
+      expect(result.reason).toBe('knowledge-missing')
+      expect(result.detail).toContain('KNOWLEDGE.md')
+    } finally { rmSync(accountDir, { recursive: true, force: true }) }
+  })
+
+  it('public + empty KNOWLEDGE ⇒ ok:false reason=knowledge-empty', () => {
+    const accountDir = makePublic({ identity: 'I', soul: 'S', knowledge: '' })
+    try {
+      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
+      expect(result.ok).toBe(false)
+      if (result.ok) return
+      expect(result.reason).toBe('knowledge-empty')
+    } finally { rmSync(accountDir, { recursive: true, force: true }) }
+  })
+
+  it('public + empty SOUL ⇒ ok:false reason=soul-empty', () => {
+    const accountDir = makePublic({ identity: 'I', soul: '', knowledge: 'K' })
+    try {
+      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
+      expect(result.ok).toBe(false)
+      if (result.ok) return
+      expect(result.reason).toBe('soul-empty')
+    } finally { rmSync(accountDir, { recursive: true, force: true }) }
+  })
+
+  it('public + empty IDENTITY ⇒ identity-unresolved (unchanged)', () => {
+    const accountDir = makePublic({ identity: '', soul: 'S', knowledge: 'K' })
+    try {
+      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
+      expect(result.ok).toBe(false)
+      if (result.ok) return
+      expect(result.reason).toBe('identity-unresolved')
+    } finally { rmSync(accountDir, { recursive: true, force: true }) }
+  })
+
+  it('admin + KNOWLEDGE.md on disk ⇒ no <knowledge> block', () => {
+    const accountDir = makeAccountDir({ admin: { identity: 'I', soul: 'S' } })
+    writeFileSync(join(accountDir, 'agents', 'admin', 'KNOWLEDGE.md'), 'admin-knowledge')
+    try {
+      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'admin' })
+      expect(result.ok).toBe(true)
+      if (!result.ok) return
+      expect(result.block).not.toContain('<knowledge>')
+      expect(result.block).not.toContain('admin-knowledge')
+    } finally { rmSync(accountDir, { recursive: true, force: true }) }
+  })
+
+  it('snapshot: full composed public prompt with a sample KNOWLEDGE.md', () => {
+    const accountDir = makePublic({
+      identity: '# Identity\nYou speak for the business.',
+      soul: '# Soul\nWarm, brief.',
+      knowledge: '# Knowledge\nOpen 9-5. Contact 01234 567890.',
+    })
+    try {
+      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
+      expect(result.ok).toBe(true)
+      if (!result.ok) return
+      expect(result.block).toMatchSnapshot()
+    } finally { rmSync(accountDir, { recursive: true, force: true }) }
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify fail** — `npx vitest run src/__tests__/system-prompt.test.ts` → FAIL (knowledge not read).
+
+- [ ] **Step 3: Implement** in `system-prompt.ts`:
+  - Add `knowledgeBytes: number` to ok:true; extend ok:false reason union.
+  - Add `knowledgeContent: string | null` param to `renderAppendBlock`; insert `<knowledge>` block after `</soul>` push, before `<about-owner>`; track + return `knowledgeBytes`.
+  - Update both internal `renderAppendBlock` callers (`runIdentityDriftAssertion`, `runSystemPromptSelfTest`) to pass `null`.
+  - In `composeAppendSystemPrompt`: on SOUL failure, `return { ok:false, reason: sources.role === 'public' ? 'soul-empty' : 'identity-unresolved', detail: soul.detail }`. When `role==='public'`, read `KNOWLEDGE.md`; on failure `return { ok:false, reason: knowledge.detail.endsWith(':empty') ? 'knowledge-empty' : 'knowledge-missing', detail: knowledge.detail }`. Pass `role==='public' ? knowledge.content : null` to `renderAppendBlock`; set `knowledgeBytes` accordingly (0 for admin).
+
+- [ ] **Step 4: Run, verify pass** — `npx vitest run src/__tests__/system-prompt.test.ts` → PASS. Review the new snapshot.
+
+- [ ] **Step 5: Commit** — `feat(public-agent): read KNOWLEDGE.md into public spawn prompt with strict refusal`
+
+---
+
+### Task 2: `pty-spawner.ts` — surface refusal reasons + per-spawn compose line
+
+**Files:**
+- Modify: `services/claude-session-manager/src/pty-spawner.ts` (`SpawnFailureReason` ~351; compose handling ~1292-1315)
+
+**Behaviours:**
+- `SpawnFailureReason` gains `'soul-empty' | 'knowledge-missing' | 'knowledge-empty'`.
+- In the `!composed.ok` branch, for the three new reasons emit `[pty-spawn] spawn-failed reason=<r> role=public slug=<agentSlug>` and return `{ ok:false, reason:<r>, stderrTail: composed.detail }`. The existing `identity-unresolved` path is unchanged.
+- Track `knowledge` in `composedBytes`. On public success emit `[pty-spawn] op=public-prompt-compose role=public slug=<agentSlug> identityBytes=N soulBytes=N knowledgeBytes=N` (in addition to the existing `compose-system-prompt-ok` line, which gains `knowledgeBytes`).
+
+- [ ] **Step 1: Implement** — extend the union; in the failure branch add a `case` for the three reasons before the identity fallthrough; add `knowledge: composed.knowledgeBytes` to `composedBytes`; append `knowledgeBytes=${composed.knowledgeBytes}` to the `compose-system-prompt-ok` log; after that log, `if (args.role === 'public') deps.logger(\`op=public-prompt-compose role=public slug=${agentSlug} identityBytes=${composed.identityBytes} soulBytes=${composed.soulBytes} knowledgeBytes=${composed.knowledgeBytes}\`)`.
+
+- [ ] **Step 2: Verify** — `npx vitest run` for csm (no test directly asserts these strings; the build + existing suite must stay green). Confirm tsc has no error on the union/result fields.
+
+- [ ] **Step 3: Commit** — `feat(public-agent): map knowledge/soul refusal reasons + emit public-prompt-compose line`
+
+---
+
+### Task 3: Templates — delete dead public SOUL + config
+
+**Files:**
+- Delete: `templates/agents/public/SOUL.md`, `templates/agents/public/config.json`
+- Keep: `templates/agents/public/IDENTITY.md`
+
+- [ ] **Step 1:** `git rm templates/agents/public/SOUL.md templates/agents/public/config.json`
+- [ ] **Step 2: Verify no live reader** — `grep -rIn 'agents/public/SOUL\|agents/public/config' --include=*.ts --include=*.sh .` returns only `setup-account.sh` lines removed in Task 4. (`smoke-boot-services.sh` and `verify-doc-impl.sh` copy/grep IDENTITY only.)
+- [ ] **Step 3: Commit** with Task 4 (template deletion is meaningless without the seed removal).
+
+---
+
+### Task 4: `setup-account.sh` — no fresh-install public agent; re-sync IDENTITY for existing
+
+**Files:**
+- Modify: `scripts/setup-account.sh` (mkdir ~38; IDENTITY block ~181-184; SOUL/config seed ~221-224)
+
+**Behaviours:**
+- Drop `"$ACCOUNT_DIR/agents/public"` from the line-38 `mkdir -p`.
+- Remove the public IDENTITY overwrite (lines 183-184) and the public SOUL/config seed (lines 221-224).
+- Add, in the agent-identities section, a loop: for each `"$ACCOUNT_DIR/agents"/*/` whose basename ≠ `admin` and which already contains `IDENTITY.md`, overwrite `IDENTITY.md` from `"$TEMPLATES_DIR/agents/public/IDENTITY.md"`; echo a re-sync line. Never create dirs; never write SOUL/KNOWLEDGE/config. Admin block untouched.
+
+- [ ] **Step 1: Implement** the three edits.
+- [ ] **Step 2: Verify fresh install** — run `setup-account.sh` against a scratch `ACCOUNT_DIR` with no `agents/public`; assert no `agents/public/` is created and `agents/admin/IDENTITY.md` exists.
+- [ ] **Step 3: Verify upgrade** — scratch `ACCOUNT_DIR` pre-seeded with `agents/sales/IDENTITY.md` (stale text) + `agents/sales/SOUL.md`; run; assert `agents/sales/IDENTITY.md` now equals the template and `agents/sales/SOUL.md` is untouched.
+- [ ] **Step 4: Commit** (with Task 3) — `refactor(installer): public agents author client-side; re-sync IDENTITY for existing dirs only`
+
+---
+
+### Task 5: `account.ts` — drop the dead `plugins` config field
+
+**Files:**
+- Modify: `ui/app/lib/claude-agent/account.ts` (`ResolvedAgentConfig` ~277; reader ~304,324; return ~395)
+- Test: `ui/app/lib/claude-agent/__tests__/spawn-context.test.ts` (trim `plugins` assertions only)
+
+**Behaviours:**
+- Remove `plugins: string[] | null` from `ResolvedAgentConfig`; remove `let plugins`, the `parsed.plugins` read, and `plugins` from the return object. Leave `knowledgeKeywords` and the budget-breakdown `plugins: 0` token field intact.
+
+- [ ] **Step 1: Find & update the test** — `grep -n 'plugins' ui/app/lib/claude-agent/__tests__/spawn-context.test.ts`; remove only the assertions reading `config.plugins`; add/confirm a case that a public `config.json` lacking `plugins` resolves and `knowledgeKeywords` is still read.
+- [ ] **Step 2: Run, verify fail/observe** — `npx vitest run ui/app/lib/claude-agent/__tests__/spawn-context.test.ts`.
+- [ ] **Step 3: Implement** the field removal in `account.ts`.
+- [ ] **Step 4: Run, verify pass** — same vitest command → PASS.
+- [ ] **Step 5: Commit** — `refactor(public-agent): drop unused plugins field from resolved agent config`
+
+---
+
+### Task 6: `public-agent-manager/SKILL.md` — correct the doc
+
+**Files:**
+- Modify: `plugins/admin/skills/public-agent-manager/SKILL.md`
+
+**Behaviours (scope item 6):**
+- (a) Table: `KNOWLEDGE.md` Required → Yes; `SOUL.md` purpose → personality + role (basic public info, capture the visitor's contact details for human follow-up — the chat equivalent of the landing-page contact form). Add a line: SOUL.md and KNOWLEDGE.md are authored entirely client-side and must be non-empty before the agent goes active; an empty one is refused at spawn. KNOWLEDGE = the business's public-facing facts at landing-page detail.
+- (b) Create step: IDENTITY.md is copied from the Rubytech template verbatim, not drafted/edited.
+- (c) Remove the `plugins` key from the `config.json` example; remove "selected plugins" from the table; delete the "Plugin Selection" section; remove the plugin-selection Create step and renumber the Create steps + every cross-reference (`Step 4/5/6/7`, `All other steps (4, 8-12)`). Update the template-create plugin pre-select bullet (plugins gone) and note IDENTITY is the fixed Rubytech template.
+- (d) Ensure no reference to a SOUL/config seed template remains.
+- Keep: `knowledgeKeywords` field, the create-form field, keyword-subscription and direct-tagging sections, projection steps.
+
+- [ ] **Step 1: Implement** the edits above.
+- [ ] **Step 2: Verify** — `grep -n 'plugins' SKILL.md` shows no `plugins` config key or Plugin Selection section (knowledgeKeywords/tagging prose may remain); Create steps are sequentially numbered with consistent cross-refs.
+- [ ] **Step 3: Commit** — `docs(public-agent): KNOWLEDGE required, IDENTITY templated, drop plugins from skill`
+
+---
+
+### Task 7: Verify — build, bundle, full suites
+
+- [ ] **Step 1:** `npm run build:claude-session-manager` → no tsc errors.
+- [ ] **Step 2:** Full csm suite `cd services/claude-session-manager && npx vitest run` → green (esp. `public-identity-template`, `pty-spawner-channels`).
+- [ ] **Step 3:** `npx vitest run ui/app/lib/claude-agent/__tests__/` → green.
+- [ ] **Step 4:** Bundle the installer payload (`maxy-code/packages/create-maxy-code` `npm run bundle`) → no runtime errors; confirm `templates/agents/public/` in the payload contains only `IDENTITY.md`.
+
+---
+
+## Self-Review
+
+- **Spec coverage:** scope 1→T1, 2→T2, 3→T3, 4→T4, 5→T5, 6→T6; verification + observability→T1/T2/T7. All covered.
+- **Out of scope (untouched):** `knowledgeKeywords` machinery, projection routes, the migrated Real Agent agent's KNOWLEDGE authoring, Pi hand-patched files.
+- **Type consistency:** `knowledgeBytes` and the three reasons named identically in T1 (composer) and T2 (spawner). `renderAppendBlock` `knowledgeContent` param threaded through all three callers.

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -499,7 +499,7 @@ eagerTool(server, "public-hostname", "Resolve this account's canonical public ho
             content: [{
                     type: "text",
                     text: `hostname: (none)\nreason: ${result.reason}\n` +
-                        `No Cloudflare tunnel is configured for this account. Run the cloudflare setup-tunnel skill before publishing externally.`,
+                        `No Cloudflare tunnel is configured for this account. Run the cloudflare skill before publishing externally.`,
                 }],
         };
     }