opencode-onboard 0.2.6 → 0.2.12

package/README.md

@@ -31,13 +31,36 @@ Most codebases have no `AGENTS.md`, no architecture docs agents can read, and no
 npx opencode-onboard@latest
 ```
 
-Requires **Node.js 18+**.
+Requires **Node.js 18+**.
+
+### Run specific steps
+
+You can also run individual maintenance/setup steps without the full wizard:
+
+```bash
+# Run one step directly
+npx opencode-onboard clean
+npx opencode-onboard platform
+npx opencode-onboard copy
+npx opencode-onboard openspec
+npx opencode-onboard skills
+npx opencode-onboard models
+npx opencode-onboard optimization
+npx opencode-onboard browser
+npx opencode-onboard metadata
+
+# Show CLI help and all commands
+npx opencode-onboard --help
+npx opencode-onboard -h
+```
+
+When available, step commands reuse context from `.opencode/opencode-onboard.json`.
 
 ---
 
 ## How it works
 
-The CLI clears the screen, shows a welcome banner, and walks you through 10 steps. The screen always shows the last 2 completed steps + the current one so you always know where you are.
+The CLI clears the screen, shows a welcome banner, and walks you through 12 steps. The screen always shows the last 2 completed steps + the current one so you always know where you are.
 
 | Step | What happens |
 |------|-------------|
@@ -48,9 +71,10 @@ The CLI clears the screen, shows a welcome banner, and walks you through 10 step
 | **5. Copy scaffolding** | Drops agents, skills, and bootstrap docs into your project |
 | **6. Init OpenSpec** | Runs `npx @fission-ai/openspec init` silently for structured change management |
 | **7. Install skills** | Installs built-in `ob-` skills + optional additional skills provider |
-| **8. Choose models** | Fetches live model list from [models.dev](https://models.dev), lets you pick plan / build / fast models with cost indicators and canonical pricing |
-| **9. Check RTK** | Verifies `rtk` is on PATH |
-| **10. Install browser plugin** | Installs `@different-ai/opencode-browser` globally for agent browser automation |
+| **8. Choose models** | Fetches live model list from [models.dev](https://models.dev), lets you pick plan / build / fast models with cost indicators and canonical pricing |
+| **9. Token optimization tools** | Optional (recommended). One checklist step for RTK check, opencode-quota setup, and caveman install (all preselected) |
+| **11. Install browser plugin** | Installs `@different-ai/opencode-browser` globally for agent browser automation |
+| **12. Write onboarding metadata** | Writes `.opencode/opencode-onboard.json` with selected setup details |
 
 When it finishes, open OpenCode in your project and type:
 
@@ -181,7 +205,7 @@ After this, every agent has accurate, persistent context about your project, no
 | **Node.js 18+** | Required |
 | **[OpenCode](https://opencode.ai)** | The agent runtime |
 | **[OpenCode Ensemble](https://github.com/hueyexe/opencode-ensemble)** | Multi-agent parallel execution |
-| **[rtk](https://github.com/rtk-ai/rtk#pre-built-binaries)** | Required for agents to run CLI commands safely |
+| **[rtk](https://github.com/rtk-ai/rtk#pre-built-binaries)** | Recommended for safer agent CLI command execution |
 | **[gh CLI](https://cli.github.com)** | GitHub platform, must be authenticated |
 | **[az CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)** + azure-devops extension | Azure DevOps platform |
 

package/content/.opencode/plugins/session-log.js

@@ -2,14 +2,29 @@ import fs from "node:fs"
 import path from "node:path"
 
 const LOG_FILE = ".agents/session-log.json"
+const SPAWN_MATCH_WINDOW_MS = 15000
+const DEBUG = process.env.SESSION_LOG_DEBUG === "true"
 
-// Per-session state: editCount and loaded skills
+// Per-session state
 const sessionState = new Map()
 
+// Lead session -> current team name
+const leadTeamBySession = new Map()
+
+// Pending spawn records waiting for a session.created match
+const pendingSpawns = []
+
+// Team -> completed session snapshots
+const completedByTeam = new Map()
+
 function ts() {
   return new Date().toISOString()
 }
 
+function nowMs() {
+  return Date.now()
+}
+
 function appendEntry(directory, entry) {
   const logPath = path.join(directory, LOG_FILE)
   const dir = path.dirname(logPath)
@@ -40,35 +55,148 @@ function addSkillToState(state, skillName) {
   return true
 }
 
-function buildTeamSkillsSummary() {
+function toNum(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v
+  if (typeof v === "string" && v.trim() !== "" && !Number.isNaN(Number(v))) return Number(v)
+  return null
+}
+
+function extractReportedTokens(obj) {
+  const out = { input: 0, output: 0, total: 0, found: false }
+  const visited = new Set()
+
+  function walk(node) {
+    if (!node || typeof node !== "object") return
+    if (visited.has(node)) return
+    visited.add(node)
+
+    for (const [k, v] of Object.entries(node)) {
+      const key = String(k).toLowerCase()
+      const n = toNum(v)
+
+      if (n !== null) {
+        if ((key.includes("input") || key.includes("prompt")) && key.includes("token")) {
+          out.input += n
+          out.found = true
+        } else if ((key.includes("output") || key.includes("completion")) && key.includes("token")) {
+          out.output += n
+          out.found = true
+        } else if (key.includes("total") && key.includes("token")) {
+          out.total += n
+          out.found = true
+        }
+      }
+
+      if (v && typeof v === "object") walk(v)
+    }
+  }
+
+  walk(obj)
+  return out
+}
+
+function estimateTokens(state) {
+  const inTokens = Math.ceil((state.charIn || 0) / 4)
+  const outTokens = Math.ceil((state.charOut || 0) / 4)
+  const base = inTokens + outTokens + Math.max(0, (state.toolCalls || 0) * 20)
+  const low = Math.max(0, Math.floor(base * 0.7))
+  const high = Math.max(low, Math.ceil(base * 1.4))
+  return { low, high }
+}
+
+function usagePayload(state) {
+  const est = estimateTokens(state)
+  const reportedIn = state.reportedInputTokens || 0
+  const reportedOut = state.reportedOutputTokens || 0
+  const reportedTotalDirect = state.reportedTotalTokens || 0
+  const reportedTotalDerived = reportedIn + reportedOut
+  const reportedTotal = reportedTotalDirect || reportedTotalDerived || 0
+
+  let method = "heuristic"
+  if (reportedTotal > 0 && (est.low > 0 || est.high > 0)) method = "mixed"
+  else if (reportedTotal > 0) method = "reported"
+
+  return {
+    inputTokensReported: reportedIn || null,
+    outputTokensReported: reportedOut || null,
+    totalTokensReported: reportedTotal || null,
+    tokenEstimateLow: est.low,
+    tokenEstimateHigh: est.high,
+    method,
+  }
+}
+
+function buildCompletedSnapshot(state, sessionId) {
+  return {
+    sessionId,
+    agent: state.agentName,
+    member: state.member || null,
+    agentType: state.agentType || null,
+    team: state.teamName || null,
+    skills: Array.from(state.skills || []).sort(),
+    usage: usagePayload(state),
+    filesEdited: state.editCount || 0,
+  }
+}
+
+function buildTeamSkillsSummary(teamName) {
+  const rows = completedByTeam.get(teamName) || []
   const byAgent = {}
-  for (const state of sessionState.values()) {
-    if (!state?.agentName) continue
-    if (!byAgent[state.agentName]) byAgent[state.agentName] = new Set()
-    for (const skill of state.skills ?? []) byAgent[state.agentName].add(skill)
+  for (const row of rows) {
+    const key = row.member || row.agent || "unknown"
+    if (!byAgent[key]) byAgent[key] = { agentType: row.agentType || null, skills: new Set() }
+    for (const s of row.skills || []) byAgent[key].skills.add(s)
   }
+  const out = {}
+  for (const [k, v] of Object.entries(byAgent)) {
+    out[k] = {
+      agentType: v.agentType,
+      skills: Array.from(v.skills).sort(),
+    }
+  }
+  return out
+}
 
-  const summary = {}
-  for (const [agent, skills] of Object.entries(byAgent)) {
-    summary[agent] = Array.from(skills).sort()
+function trackCompletedByTeam(snapshot) {
+  if (!snapshot.team) return
+  if (!completedByTeam.has(snapshot.team)) completedByTeam.set(snapshot.team, [])
+  completedByTeam.get(snapshot.team).push(snapshot)
+}
+
+function enqueuePendingSpawn(leadSessionId, args) {
+  pendingSpawns.push({
+    leadSessionId,
+    at: nowMs(),
+    member: args?.name || null,
+    agentType: args?.agent || null,
+    teamName: leadTeamBySession.get(leadSessionId) || null,
+  })
+}
+
+function matchPendingSpawn() {
+  const now = nowMs()
+  // Drop expired pending spawns first
+  for (let i = pendingSpawns.length - 1; i >= 0; i--) {
+    if (now - pendingSpawns[i].at > SPAWN_MATCH_WINDOW_MS) pendingSpawns.splice(i, 1)
   }
-  return summary
+  if (pendingSpawns.length === 0) return null
+  return pendingSpawns.shift()
 }
 
-// Maps ensemble tool name → function that extracts the log entry fields from args
+// Maps ensemble tool name -> function that extracts log entry fields from args
 const ENSEMBLE_TOOL_HANDLERS = {
-  team_create:         (args) => ({ action: "team-created",        team: args.name }),
-  team_spawn:          (args) => ({ action: "teammate-spawned",    name: args.name, agentType: args.agent }),
-  team_shutdown:       (args) => ({ action: "teammate-shutdown",   name: args.name }),
-  team_merge:          (args) => ({ action: "teammate-merged",     name: args.name }),
-  team_cleanup:        ()     => ({ action: "team-cleanup" }),
-  team_status:         ()     => ({ action: "team-status-checked" }),
-  team_results:        (args) => ({ action: "team-results-read",   from: args.from }),
-  team_message:        (args) => ({ action: "team-message",        to: args.to ?? "lead", preview: String(args.text ?? "").slice(0, 120) }),
-  team_broadcast:      (args) => ({ action: "team-broadcast",      preview: String(args.text ?? "").slice(0, 120) }),
-  team_tasks_add:      (args) => ({ action: "tasks-added",         count: Array.isArray(args.tasks) ? args.tasks.length : "?" }),
-  team_tasks_complete: (args) => ({ action: "task-completed",      taskId: args.task_id }),
-  team_claim:          (args) => ({ action: "task-claimed",        taskId: args.task_id }),
+  team_create:         (args) => ({ action: "team-created", team: args.name }),
+  team_spawn:          (args) => ({ action: "teammate-spawned", name: args.name, agentType: args.agent }),
+  team_shutdown:       (args) => ({ action: "teammate-shutdown", name: args.name }),
+  team_merge:          (args) => ({ action: "teammate-merged", name: args.name }),
+  team_cleanup:        () => ({ action: "team-cleanup" }),
+  team_status:         () => ({ action: "team-status-checked" }),
+  team_results:        (args) => ({ action: "team-results-read", from: args.from }),
+  team_message:        (args) => ({ action: "team-message", to: args.to ?? "lead", preview: String(args.text ?? "").slice(0, 120) }),
+  team_broadcast:      (args) => ({ action: "team-broadcast", preview: String(args.text ?? "").slice(0, 120) }),
+  team_tasks_add:      (args) => ({ action: "tasks-added", count: Array.isArray(args.tasks) ? args.tasks.length : "?" }),
+  team_tasks_complete: (args) => ({ action: "task-completed", taskId: args.task_id }),
+  team_claim:          (args) => ({ action: "task-claimed", taskId: args.task_id }),
 }
 
 export const SessionLogPlugin = async ({ client, directory }) => {
@@ -81,10 +209,35 @@ export const SessionLogPlugin = async ({ client, directory }) => {
 
           const res = await client.session.get({ path: { id: sessionId } })
           const session = res?.data
-          const agentName = resolveAgentName(session)
+          const fallbackAgent = resolveAgentName(session)
+          const spawnMatch = matchPendingSpawn()
+
+          const state = {
+            agentName: spawnMatch?.member || fallbackAgent,
+            member: spawnMatch?.member || null,
+            agentType: spawnMatch?.agentType || null,
+            teamName: spawnMatch?.teamName || null,
+            editCount: 0,
+            skills: new Set(),
+            startedAtMs: nowMs(),
+            toolCalls: 0,
+            charIn: 0,
+            charOut: 0,
+            reportedInputTokens: 0,
+            reportedOutputTokens: 0,
+            reportedTotalTokens: 0,
+          }
 
-          sessionState.set(sessionId, { agentName, editCount: 0, skills: new Set() })
-          appendEntry(directory, { ts: ts(), agent: agentName, action: "started", sessionId })
+          sessionState.set(sessionId, state)
+          appendEntry(directory, {
+            ts: ts(),
+            agent: state.agentName,
+            member: state.member,
+            agentType: state.agentType,
+            team: state.teamName,
+            action: "started",
+            sessionId,
+          })
         }
 
         if (event?.type === "file.edited") {
@@ -100,9 +253,21 @@ export const SessionLogPlugin = async ({ client, directory }) => {
           const state = sessionState.get(sessionId)
           if (!state) return
 
-          const { agentName, editCount } = state
-          const skills = Array.from(state.skills ?? []).sort()
-          appendEntry(directory, { ts: ts(), agent: agentName, action: "completed", filesEdited: editCount, skills })
+          const skills = Array.from(state.skills || []).sort()
+          const usage = usagePayload(state)
+          appendEntry(directory, {
+            ts: ts(),
+            agent: state.agentName,
+            member: state.member,
+            agentType: state.agentType,
+            team: state.teamName,
+            action: "completed",
+            filesEdited: state.editCount,
+            skills,
+            usage,
+          })
+
+          trackCompletedByTeam(buildCompletedSnapshot(state, sessionId))
           sessionState.delete(sessionId)
         }
       } catch (_) {}
@@ -117,13 +282,49 @@ export const SessionLogPlugin = async ({ client, directory }) => {
         if (!state) return
 
         const tool = input?.tool
+        const args = input?.args ?? {}
+
+        state.toolCalls++
+        state.charIn += JSON.stringify(args).length
+        state.charOut += JSON.stringify(output ?? {}).length
+
+        const reportedIn = extractReportedTokens(input)
+        const reportedOut = extractReportedTokens(output)
+        if (reportedIn.found) {
+          state.reportedInputTokens += reportedIn.input
+          state.reportedOutputTokens += reportedIn.output
+          state.reportedTotalTokens += reportedIn.total
+        }
+        if (reportedOut.found) {
+          state.reportedInputTokens += reportedOut.input
+          state.reportedOutputTokens += reportedOut.output
+          state.reportedTotalTokens += reportedOut.total
+        }
+
+        if (DEBUG && !reportedIn.found && !reportedOut.found && tool !== "read") {
+          appendEntry(directory, {
+            ts: ts(),
+            agent: state.agentName,
+            action: "debug-no-token-metrics",
+            tool,
+          })
+        }
 
         // Track skill loads via skill tool (primary)
         if (tool === "skill") {
           const skillName = input?.args?.name
           const added = addSkillToState(state, skillName)
           if (added) {
-            appendEntry(directory, { ts: ts(), agent: state.agentName, action: "skill-loaded", skill: skillName, source: "skill-tool" })
+            appendEntry(directory, {
+              ts: ts(),
+              agent: state.agentName,
+              member: state.member,
+              agentType: state.agentType,
+              team: state.teamName,
+              action: "skill-loaded",
+              skill: skillName,
+              source: "skill-tool",
+            })
           }
           return
         }
@@ -136,23 +337,53 @@ export const SessionLogPlugin = async ({ client, directory }) => {
             const skillName = match[1]
             const added = addSkillToState(state, skillName)
             if (added) {
-              appendEntry(directory, { ts: ts(), agent: state.agentName, action: "skill-loaded", skill: skillName, source: "read-skill-file" })
+              appendEntry(directory, {
+                ts: ts(),
+                agent: state.agentName,
+                member: state.member,
+                agentType: state.agentType,
+                team: state.teamName,
+                action: "skill-loaded",
+                skill: skillName,
+                source: "read-skill-file",
+              })
             }
           }
           return
         }
 
-        const args = input?.args ?? {}
-
         // Track ensemble tool calls
         const ensembleHandler = ENSEMBLE_TOOL_HANDLERS[tool]
         if (!ensembleHandler) return
 
-        const entry = { ts: ts(), agent: state.agentName, ...ensembleHandler(args) }
+        const entry = {
+          ts: ts(),
+          agent: state.agentName,
+          member: state.member,
+          agentType: state.agentType,
+          team: state.teamName,
+          ...ensembleHandler(args),
+        }
         appendEntry(directory, entry)
 
+        if (tool === "team_create") {
+          leadTeamBySession.set(sessionId, args?.name || null)
+          state.teamName = args?.name || state.teamName
+        }
+
+        if (tool === "team_spawn") {
+          enqueuePendingSpawn(sessionId, args)
+        }
+
         if (tool === "team_cleanup") {
-          appendEntry(directory, { ts: ts(), agent: state.agentName, action: "team-skills-summary", byAgent: buildTeamSkillsSummary() })
+          const teamName = state.teamName || leadTeamBySession.get(sessionId)
+          appendEntry(directory, {
+            ts: ts(),
+            agent: state.agentName,
+            action: "team-skills-summary",
+            team: teamName || null,
+            byAgent: teamName ? buildTeamSkillsSummary(teamName) : {},
+          })
         }
       } catch (_) {}
     },