bopodev-api 0.1.32 → 0.1.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bopodev-api",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -17,18 +17,20 @@
     "fflate": "^0.8.2",
     "multer": "^2.1.1",
     "nanoid": "^5.1.5",
+    "turndown": "^7.2.2",
     "ws": "^8.19.0",
     "yaml": "^2.8.3",
     "zod": "^4.1.5",
-    "bopodev-agent-sdk": "0.1.32",
-    "bopodev-contracts": "0.1.32",
-    "bopodev-db": "0.1.32"
+    "bopodev-agent-sdk": "0.1.33",
+    "bopodev-db": "0.1.33",
+    "bopodev-contracts": "0.1.33"
   },
   "devDependencies": {
     "@types/archiver": "^7.0.0",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/multer": "^2.1.0",
+    "@types/turndown": "^5.0.6",
     "@types/ws": "^8.18.1",
     "tsx": "^4.20.5"
   },

package/src/lib/agent-config.ts

@@ -1,4 +1,9 @@
-import { AgentRuntimeConfigSchema, type AgentRuntimeConfig, type ThinkingEffort } from "bopodev-contracts";
+import {
+  AgentRuntimeConfigSchema,
+  companySkillAllowlistOnly,
+  type AgentRuntimeConfig,
+  type ThinkingEffort
+} from "bopodev-contracts";
 import { normalizeAbsolutePath } from "./instance-paths";
 
 export type LegacyRuntimeFields = {
@@ -16,6 +21,8 @@ export type LegacyRuntimeFields = {
     allowWebSearch?: boolean;
   };
   runtimeEnv?: Record<string, string>;
+  /** Company skill ids only (bundled ids are stripped on normalize). */
+  enabledSkillIds?: string[] | null;
 };
 
 export type NormalizedRuntimeConfig = {
@@ -26,6 +33,8 @@ export type NormalizedRuntimeConfig = {
   runtimeModel?: string;
   runtimeThinkingEffort: ThinkingEffort;
   bootstrapPrompt?: string;
+  /** Omitted = inject all skills (legacy). Present = company skill ids only; bundled skills are always injected. */
+  enabledSkillIds?: string[];
   runtimeTimeoutSec: number;
   interruptGraceSec: number;
   runPolicy: {
@@ -109,6 +118,9 @@ export function normalizeRuntimeConfig(input: {
   if (legacy.runPolicy !== undefined) {
     merged.runPolicy = legacy.runPolicy;
   }
+  if (legacy.enabledSkillIds !== undefined) {
+    merged.enabledSkillIds = legacy.enabledSkillIds;
+  }
 
   const parsed = AgentRuntimeConfigSchema.partial().parse({
     ...merged,
@@ -131,7 +143,11 @@ export function normalizeRuntimeConfig(input: {
     runPolicy: {
       sandboxMode: parsed.runPolicy?.sandboxMode ?? "workspace_write",
       allowWebSearch: parsed.runPolicy?.allowWebSearch ?? false
-    }
+    },
+    enabledSkillIds:
+      parsed.enabledSkillIds === null || parsed.enabledSkillIds === undefined
+        ? undefined
+        : companySkillAllowlistOnly(parsed.enabledSkillIds)
   };
 }
 
@@ -165,6 +181,8 @@ export function parseRuntimeConfigFromAgentRow(agent: Record<string, unknown>):
     runtimeModel,
     runtimeThinkingEffort: parseThinkingEffort(agent.runtimeThinkingEffort),
     bootstrapPrompt: toText(agent.bootstrapPrompt),
+    enabledSkillIds:
+      fallback.enabledSkillIds === undefined ? undefined : companySkillAllowlistOnly(fallback.enabledSkillIds),
     runtimeTimeoutSec: Math.max(0, timeoutSec),
     interruptGraceSec: Math.max(0, toNumber(agent.interruptGraceSec) ?? 15),
     runPolicy
@@ -187,14 +205,18 @@ export function runtimeConfigToDb(runtime: NormalizedRuntimeConfig) {
 }
 
 export function runtimeConfigToStateBlobPatch(runtime: NormalizedRuntimeConfig) {
+  const runtimePatch: Record<string, unknown> = {
+    command: runtime.runtimeCommand,
+    args: runtime.runtimeArgs,
+    cwd: runtime.runtimeCwd,
+    env: runtime.runtimeEnv,
+    timeoutMs: runtime.runtimeTimeoutSec > 0 ? runtime.runtimeTimeoutSec * 1000 : undefined
+  };
+  if (runtime.enabledSkillIds !== undefined) {
+    runtimePatch.enabledSkillIds = runtime.enabledSkillIds;
+  }
   return {
-    runtime: {
-      command: runtime.runtimeCommand,
-      args: runtime.runtimeArgs,
-      cwd: runtime.runtimeCwd,
-      env: runtime.runtimeEnv,
-      timeoutMs: runtime.runtimeTimeoutSec > 0 ? runtime.runtimeTimeoutSec * 1000 : undefined
-    },
+    runtime: runtimePatch,
     promptTemplate: runtime.bootstrapPrompt
   };
 }
@@ -208,6 +230,7 @@ function parseRuntimeFromStateBlob(raw: unknown) {
       env?: Record<string, string>;
       model?: string;
       timeoutMs?: number;
+      enabledSkillIds?: string[];
     };
   }
   try {
@@ -219,6 +242,7 @@ function parseRuntimeFromStateBlob(raw: unknown) {
         env?: unknown;
         model?: unknown;
         timeoutMs?: unknown;
+        enabledSkillIds?: unknown;
       };
     };
     const runtime = parsed.runtime ?? {};
@@ -228,13 +252,37 @@ function parseRuntimeFromStateBlob(raw: unknown) {
       cwd: typeof runtime.cwd === "string" ? runtime.cwd : undefined,
       env: toRecord(runtime.env),
       model: typeof runtime.model === "string" && runtime.model.trim().length > 0 ? runtime.model.trim() : undefined,
-      timeoutMs: toNumber(runtime.timeoutMs)
+      timeoutMs: toNumber(runtime.timeoutMs),
+      enabledSkillIds: parseEnabledSkillIdsFromState(runtime.enabledSkillIds)
     };
   } catch {
     return {};
   }
 }
 
+function parseEnabledSkillIdsFromState(raw: unknown): string[] | undefined {
+  if (!Array.isArray(raw)) {
+    return undefined;
+  }
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const entry of raw) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+    const trimmed = entry.trim();
+    if (!trimmed || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    out.push(trimmed);
+    if (out.length >= 64) {
+      break;
+    }
+  }
+  return out;
+}
+
 function parseStringArray(raw: unknown) {
   if (typeof raw !== "string") {
     return null;

package/src/lib/builtin-bopo-skills/bopodev-control-plane.md

@@ -0,0 +1,123 @@
+---
+name: bopodev-control-plane
+description: >
+  Coordinate heartbeat work through a control-plane API: assignments, checkout,
+  comments, status updates, approvals, and delegation. Use this for orchestration
+  only, not domain implementation itself.
+---
+
+# BopoDev Control Plane Skill
+
+Use this skill when the agent must interact with the control plane for issue
+coordination (assignment management, workflow state, and delegation).
+
+Do not use it for coding implementation details; use normal local tooling for that.
+
+## Required context
+
+Expected env variables:
+
+- `BOPODEV_AGENT_ID`
+- `BOPODEV_COMPANY_ID`
+- `BOPODEV_RUN_ID`
+- `BOPODEV_API_BASE_URL`
+- `BOPODEV_REQUEST_HEADERS_JSON` (fallback JSON map for required request headers)
+- `BOPODEV_ACTOR_TYPE`
+- `BOPODEV_ACTOR_ID`
+- `BOPODEV_ACTOR_COMPANIES`
+- `BOPODEV_ACTOR_PERMISSIONS`
+
+Wake context (optional):
+
+- `BOPODEV_TASK_ID`
+- `BOPODEV_WAKE_REASON`
+- `BOPODEV_WAKE_COMMENT_ID`
+- `BOPODEV_APPROVAL_ID`
+- `BOPODEV_APPROVAL_STATUS`
+- `BOPODEV_LINKED_ISSUE_IDS`
+
+If control-plane connectivity is unavailable, do not attempt control-plane mutations.
+Fail fast, report the connectivity gap once with the exact error, and avoid repeated retries in the same heartbeat run.
+
+## Heartbeat procedure
+
+1. Resolve identity from env: `BOPODEV_AGENT_ID`, `BOPODEV_COMPANY_ID`, `BOPODEV_RUN_ID`.
+2. If approval-related wake context exists (env or heartbeat prompt), process linked approvals first.
+3. Use assigned issues from heartbeat prompt as primary work queue.
+4. Prioritize `in_progress`, then `todo`; only revisit `blocked` with new context.
+5. Read issue comments for current context before mutating status.
+6. Do the work.
+7. Publish progress and update final state (`done`, `blocked`, `in_review`).
+8. Delegate through subtasks when decomposition is needed.
+
+## API usage pattern
+
+All API routes are rooted at `BOPODEV_API_BASE_URL` (no `/api` prefix in this project).
+
+Use direct env vars for request headers (preferred, deterministic):
+
+- `x-company-id`
+- `x-actor-type`
+- `x-actor-id`
+- `x-actor-companies`
+- `x-actor-permissions`
+
+Recommended curl header pattern (do not parse JSON first):
+
+`curl -sS -H "x-company-id: $BOPODEV_COMPANY_ID" -H "x-actor-type: $BOPODEV_ACTOR_TYPE" -H "x-actor-id: $BOPODEV_ACTOR_ID" -H "x-actor-companies: $BOPODEV_ACTOR_COMPANIES" -H "x-actor-permissions: $BOPODEV_ACTOR_PERMISSIONS" ...`
+
+Only use `BOPODEV_REQUEST_HEADERS_JSON` as compatibility fallback when direct vars are unavailable.
+
+Prefer direct header flags from env when scripting requests. Do not assume `python` is installed.
+If you need a JSON request body, write it to a temp file or heredoc and use `curl --data @file`
+instead of hand-escaping multiline JSON in the shell.
+The runtime shell is `zsh` on macOS. Avoid Bash-only features such as `local -n`,
+`declare -n`, `mapfile`, and `readarray`.
+
+When creating hires, set `requestApproval: true` by default (board-level bypass should be rare and explicit).
+
+## Critical safety rules
+
+- Heartbeat-assigned issues may already be claimed by the current run. Do not call a
+  nonexistent checkout endpoint in this project.
+- Never assume `POST /issues/{issueId}/checkout` exists here.
+- Never assume `GET /agents/{agentId}` exists here.
+- Never retry ownership conflicts (`409`).
+- Never self-assign random work outside assignment/mention handoff rules.
+- Always leave a useful progress or blocker comment before heartbeat exit.
+- If blocked, update state to `blocked` and include a specific unblock path.
+- Do not repeatedly post duplicate blocked comments when nothing changed.
+- Escalate through reporting chain for cross-team blockers.
+- Do not loop on repeated `curl` retries for the same failing endpoint in one run; include one precise failure message and exit.
+
+## Comment style
+
+When adding comments, use concise markdown:
+
+- one short status line
+- bullet list of what changed or what is blocked
+- links to related entities when available (issue/approval/agent/run)
+
+## Quick endpoint reference
+
+| Action | Endpoint |
+| --- | --- |
+| List agents | `GET /agents` |
+| Update agent | `PUT /agents/{agentId}` |
+| Hire request (approval-backed) | `POST /agents` with `requestApproval: true` |
+| List approvals | `GET /governance/approvals` |
+| Read issue comments | `GET /issues/{issueId}/comments` |
+| Add issue comment | `POST /issues/{issueId}/comments` |
+| Update issue | `PUT /issues/{issueId}` |
+| Create subtask issue | `POST /issues` |
+
+## Important route notes
+
+- To inspect your own agent, use `GET /agents` and filter by id locally.
+- `GET /agents` returns a wrapped envelope: `{ "ok": true, "data": [...] }`.
+- Treat any non-envelope shape as a hard failure for this run.
+- Recommended deterministic filter:
+  `jq -er --arg id "$BOPODEV_AGENT_ID" '.data | if type=="array" then . else error("invalid_agents_payload") end | map(select((.id? // "") == $id)) | .[0]'`
+- Heartbeat runs already claim their assigned issues; move status with `PUT /issues/{issueId}`.
+- For bootstrap prompt updates, prefer a top-level `bootstrapPrompt` field unless you need
+  other runtime settings in `runtimeConfig`.

package/src/lib/builtin-bopo-skills/bopodev-create-agent.md

@@ -0,0 +1,90 @@
+---
+name: bopodev-create-agent
+description: >
+  Hire agents through governance-aware control-plane flow: inspect adapter
+  options, draft configuration, and submit approval-backed hire requests.
+---
+
+# BopoDev Create Agent Skill
+
+Use this skill when creating or revising agent hires in the control plane.
+
+## Preconditions
+
+One of the following must be true:
+
+- caller has board access, or
+- caller has agent creation permission.
+
+If permission is missing, escalate to a manager/board actor.
+
+## Standard workflow
+
+1. Confirm identity and active company context.
+2. Compare existing agent configurations from `GET /agents` for reusable patterns.
+3. Choose role, provider, reporting line, and runtime heartbeat profile.
+4. Draft agent prompt/instructions with role-scoped responsibilities.
+5. Set `capabilities` (required for every hire): a short plain-language line for the org chart and heartbeat team roster—what this agent does for delegation. If the request came from a delegated hiring issue, prefer `delegationIntent.requestedCapabilities` or the issue metadata `delegatedHiringIntent.requestedCapabilities` when present; otherwise write one from the role and brief.
+6. Submit hire request and capture approval linkage.
+7. Track approval state and post follow-up comments with links.
+8. On approval wake, close or update linked issues accordingly.
+
+## Payload checklist
+
+Before submission, ensure payload includes:
+
+- `name`
+- `role`
+- `providerType`
+- `heartbeatCron`
+- `monthlyBudgetUsd`
+- optional `managerAgentId`
+- optional `canHireAgents`
+- `capabilities` (short description for org chart and team roster; include on every hire)
+- optional `bootstrapPrompt` (extra standing instructions only; operating docs are injected via heartbeat env) or supported `runtimeConfig`
+- `requestApproval` (defaults to `true`; keep `true` for routine hires)
+
+Do not use unsupported fields such as:
+
+- `adapterType`
+- `adapterConfig`
+- `reportsTo`
+- arbitrary nested `runtimeConfig` keys outside the supported runtime contract
+
+## Minimal approved shape
+
+For a Codex hire, prefer this shape:
+
+```json
+{
+  "name": "Founding Engineer",
+  "role": "Founding Engineer",
+  "capabilities": "Ships product changes with tests, clear handoffs, and accurate issue updates.",
+  "providerType": "codex",
+  "managerAgentId": "<manager-agent-id>",
+  "heartbeatCron": "*/5 * * * *",
+  "monthlyBudgetUsd": 100,
+  "bootstrapPrompt": "Optional: prefer small PRs and note blockers in employee_comment.",
+  "requestApproval": true
+}
+```
+
+If you need multiline prompt text, write the JSON to a temp file or heredoc and submit with
+`curl --data @file` instead of shell-escaping the body inline.
+The runtime shell is `zsh` on macOS, so keep helper scripts POSIX/zsh-compatible and avoid
+Bash-only features like `local -n`, `declare -n`, `mapfile`, and `readarray`.
+
+## Governance rules
+
+- Use approval-backed hiring by default.
+- Do not bypass governance for routine hires (only board-level operators should bypass intentionally).
+- If board feedback requests revisions, resubmit with explicit deltas.
+- Keep approval threads updated with issue/agent/approval links.
+
+## Quality bar
+
+- Prefer proven adapter/runtime templates over one-off configs.
+- Keep prompts operational and bounded to the role.
+- Do not store plaintext secrets unless strictly required.
+- Validate reporting chain and company ownership before submission.
+- Use deterministic, auditable language in approval comments.

package/src/lib/builtin-bopo-skills/index.ts

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BUILTIN_BOPO_SKILL_IDS } from "bopodev-contracts";
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+
+export type BuiltinBopoSkill = {
+  id: string;
+  title: string;
+  content: string;
+};
+
+const BUILTIN_TITLES: Record<string, string> = {
+  "bopodev-control-plane": "Bopo control plane",
+  "bopodev-create-agent": "Bopo create agent",
+  "para-memory-files": "PARA memory files"
+};
+
+function readBundled(id: string, title: string): BuiltinBopoSkill {
+  try {
+    const content = readFileSync(join(DIR, `${id}.md`), "utf8");
+    return { id, title, content };
+  } catch {
+    return {
+      id,
+      title,
+      content: `# ${title}\n\nBuilt-in skill text is not available in this build (missing bundled copy of \`${id}.md\`).\n`
+    };
+  }
+}
+
+/** Injected into local agent runtimes alongside company `skills/`. Read-only in Settings UI. */
+export const BUILTIN_BOPO_SKILLS: BuiltinBopoSkill[] = BUILTIN_BOPO_SKILL_IDS.map((id) =>
+  readBundled(id, BUILTIN_TITLES[id] ?? id)
+);

package/src/lib/builtin-bopo-skills/para-memory-files.md

@@ -0,0 +1,48 @@
+---
+name: para-memory-files
+description: >
+  File-backed memory using PARA (Projects, Areas, Resources, Archives). Use for
+  persistent recall across sessions: durable facts, daily notes, and user habits.
+---
+
+# PARA Memory Files
+
+Use this skill whenever context must survive beyond the current runtime session.
+
+## Memory layers
+
+1. Knowledge graph (`life/`)
+   - entity folders with `summary.md` and `items.yaml`
+   - durable, queryable facts
+2. Daily notes (`memory/YYYY-MM-DD.md`)
+   - chronological event log
+   - temporary observations before curation
+3. Tacit memory (`MEMORY.md`)
+   - user preferences, work style, collaboration patterns
+
+## PARA organization
+
+- `projects/`: active efforts with goals/deadlines
+- `areas/`: ongoing responsibilities
+- `resources/`: reusable reference knowledge
+- `archives/`: inactive entities moved from other buckets
+
+## Operating rules
+
+- Write durable facts immediately to `items.yaml`.
+- Keep `summary.md` short and regenerate from active facts.
+- Never delete facts; supersede with status and replacement reference.
+- Move inactive entities to `archives` rather than removing them.
+- Prefer writing to disk over relying on transient model context.
+
+## Recall workflow
+
+1. Capture raw event in daily note.
+2. Promote durable facts into entity files.
+3. Update entity summary from durable facts.
+4. Update tacit memory when user operating patterns become clear.
+
+## Planning notes
+
+- Store shared plans in project `plans/` where collaborators can access them.
+- Mark superseded plans to prevent stale guidance drift.

package/src/lib/instance-paths.ts

@@ -61,6 +61,11 @@ export function resolveCompanyProjectsWorkspacePath(companyId: string) {
   return join(resolveBopoInstanceRoot(), "workspaces", safeCompanyId);
 }
 
+/** Company-managed runtime skills (`skills/<id>/SKILL.md`), exportable with company zip. */
+export function resolveCompanySkillsPath(companyId: string) {
+  return join(resolveCompanyProjectsWorkspacePath(companyId), "skills");
+}
+
 export function resolveAgentFallbackWorkspacePath(companyId: string, agentId: string) {
   const safeCompanyId = assertPathSegment(companyId, "companyId");
   const safeAgentId = assertPathSegment(agentId, "agentId");

package/src/routes/agents.ts

@@ -62,7 +62,8 @@ const legacyRuntimeConfigSchema = z.object({
       sandboxMode: z.enum(["workspace_write", "full_access"]).optional(),
       allowWebSearch: z.boolean().optional()
     })
-    .optional()
+    .optional(),
+  enabledSkillIds: z.array(z.string().min(1)).max(64).nullable().optional()
 });
 
 const createAgentSchema = AgentCreateRequestSchema.extend({
@@ -118,7 +119,8 @@ const UPDATE_AGENT_ALLOWED_KEYS = new Set([
   "runtimeTimeoutSec",
   "interruptGraceSec",
   "runtimeEnv",
-  "runPolicy"
+  "runPolicy",
+  "enabledSkillIds"
 ]);
 const UPDATE_RUNTIME_CONFIG_ALLOWED_KEYS = new Set([
   "runtimeCommand",
@@ -130,15 +132,18 @@ const UPDATE_RUNTIME_CONFIG_ALLOWED_KEYS = new Set([
   "bootstrapPrompt",
   "runtimeTimeoutSec",
   "interruptGraceSec",
-  "runPolicy"
+  "runPolicy",
+  "enabledSkillIds"
 ]);
 
 function toAgentResponse(agent: Record<string, unknown>) {
+  const rt = parseRuntimeConfigFromAgentRow(agent);
   return {
     ...agent,
     monthlyBudgetUsd:
       typeof agent.monthlyBudgetUsd === "number" ? agent.monthlyBudgetUsd : Number(agent.monthlyBudgetUsd ?? 0),
-    usedBudgetUsd: typeof agent.usedBudgetUsd === "number" ? agent.usedBudgetUsd : Number(agent.usedBudgetUsd ?? 0)
+    usedBudgetUsd: typeof agent.usedBudgetUsd === "number" ? agent.usedBudgetUsd : Number(agent.usedBudgetUsd ?? 0),
+    enabledSkillIds: rt.enabledSkillIds === undefined ? null : rt.enabledSkillIds
   };
 }
 
@@ -400,7 +405,8 @@ export function createAgentsRouter(ctx: AppContext) {
           runtimeTimeoutSec: parsed.data.runtimeTimeoutSec,
           interruptGraceSec: parsed.data.interruptGraceSec,
           runtimeEnv: parsed.data.runtimeEnv,
-          runPolicy: parsed.data.runPolicy
+          runPolicy: parsed.data.runPolicy,
+          enabledSkillIds: parsed.data.enabledSkillIds
         },
         defaultRuntimeCwd
       });
@@ -408,6 +414,12 @@ export function createAgentsRouter(ctx: AppContext) {
     } catch (error) {
       return sendError(res, String(error), 422);
     }
+    const rc = parsed.data.runtimeConfig;
+    const hasEnabledSkillIdsKey =
+      rc !== undefined && rc !== null && typeof rc === "object" && "enabledSkillIds" in rc;
+    if (!hasEnabledSkillIdsKey && parsed.data.enabledSkillIds === undefined) {
+      runtimeConfig = { ...runtimeConfig, enabledSkillIds: [] };
+    }
     runtimeConfig.runtimeModel = await resolveOpencodeRuntimeModel(parsed.data.providerType, runtimeConfig);
     runtimeConfig.runtimeModel = resolveRuntimeModelForProvider(parsed.data.providerType, runtimeConfig.runtimeModel);
     if (!ensureNamedRuntimeModel(parsed.data.providerType, runtimeConfig.runtimeModel)) {
@@ -560,7 +572,8 @@ export function createAgentsRouter(ctx: AppContext) {
       parsed.data.runtimeTimeoutSec !== undefined ||
       parsed.data.interruptGraceSec !== undefined ||
       parsed.data.runtimeEnv !== undefined ||
-      parsed.data.runPolicy !== undefined;
+      parsed.data.runPolicy !== undefined ||
+      parsed.data.enabledSkillIds !== undefined;
     try {
       let nextRuntime = {
         ...existingRuntime,
@@ -581,7 +594,8 @@ export function createAgentsRouter(ctx: AppContext) {
                 runtimeTimeoutSec: parsed.data.runtimeTimeoutSec ?? existingRuntime.runtimeTimeoutSec,
                 interruptGraceSec: parsed.data.interruptGraceSec,
                 runtimeEnv: parsed.data.runtimeEnv,
-                runPolicy: parsed.data.runPolicy
+                runPolicy: parsed.data.runPolicy,
+                enabledSkillIds: parsed.data.enabledSkillIds
               }
             })
           : {})