farhoodlabs/paperclip-adapter-opencode-k8s
8
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: instructionsFilePath config field + skill bundle materialization

Browse Source 
- config-schema: add instructionsFilePath UI field (Core group, text type)
- server/index.ts: set supportsInstructionsBundle=true, instructionsPathKey="instructionsFilePath"
- execute.ts: read instructionsFilePath file + desired skill markdown files from PVC; pass to buildJobManifest as instructionsContent / skillsBundleContent
- job-manifest.ts: accept instructionsContent + skillsBundleContent in JobBuildInput; prepend both to prompt via joinPromptSections; add instructionsChars + skillsBundleChars to promptMetrics
- index.ts: document instructionsFilePath and skills injection in agentConfigurationDoc
- CLAUDE.md: document skill materialization (ephemeral mode) and instructionsFilePath field
- Bump version to 0.1.18

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Chris Farhood
2026-04-24 22:06:07 +00:00
committed by Blake Middleware [agent]
parent 13c2a3032b
commit 0fcc6f01c1
6 changed files with 37 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+16 -6
View File
@@ -25,16 +25,26 @@ This is a Paperclip adapter plugin that runs OpenCode agents as isolated Kuberne
1. **Concurrency guard** — checks for existing running Jobs for the same agent (shared PVC/session enforcement)
2. **Self-pod introspection** (`getSelfPodInfo`) — queries own pod to inherit image, imagePullSecrets, DNS config, PVC mount, and all env vars from the Deployment
3. **Job manifest build** (`buildJobManifest`) — constructs a K8s Job with:
3. **Instructions + skill bundle resolution** — reads `instructionsFilePath` from config and desired skill markdown files from the PVC; content is prepended to the prompt at build time
4. **Job manifest build** (`buildJobManifest`) — constructs a K8s Job with:
- Init container (busybox) that writes the prompt to an emptyDir volume
- Main opencode container that pipes the prompt via stdin
- Prompt assembled as: `[instructionsContent] + [skillsBundleContent] + bootstrapPrompt + wakePrompt + sessionHandoff + heartbeatPrompt`
- Inherited env vars layered: Deployment env → PAPERCLIP_* vars → user overrides
- Resource requests/limits, security contexts, tolerations, nodeSelector applied from config
4. **Job creation** — creates the Job in the target namespace
5. **Pod scheduling wait** — polls for the pod to be scheduled, checking init container states and image pull issues
6. **Log streaming + completion wait** — streams pod logs to the Paperclip UI while waiting for Job completion (with configurable timeout)
7. **JSONL parsing** (`parseOpenCodeJsonl`) — extracts session ID, usage tokens, cost, summary, and errors from OpenCode JSONL output
8. **Result synthesis** — returns exit code, usage metrics, session params for resume, and billing type inference
5. **Job creation** — creates the Job in the target namespace
6. **Pod scheduling wait** — polls for the pod to be scheduled, checking init container states and image pull issues
7. **Log streaming + completion wait** — streams pod logs to the Paperclip UI while waiting for Job completion (with configurable timeout)
8. **JSONL parsing** (`parseOpenCodeJsonl`) — extracts session ID, usage tokens, cost, summary, and errors from OpenCode JSONL output
9. **Result synthesis** — returns exit code, usage metrics, session params for resume, and billing type inference
### Skill Materialization (`src/server/skills.ts` + `src/server/execute.ts`)
Skills operate in **ephemeral** mode: no symlinks are written to PVC. Instead, `execute()` reads the markdown content of each desired skill at run time using `readPaperclipRuntimeSkillEntries` + `entry.source`, concatenates them (separated by `---`), and passes the bundle to `buildJobManifest` as `skillsBundleContent`. The content is prepended to the prompt so OpenCode receives it as system context.
### `instructionsFilePath` Config Field
Set `instructionsFilePath` to an absolute path (typically on the PVC, e.g. `/paperclip/.claude/projects/COMPANY/agents/AGENT/AGENTS.md`). The file is read by the adapter server before Job creation and its content prepended to every run prompt. `supportsInstructionsBundle: true` enables the Paperclip UI bundle editor for this field.
### Key State: SelfPodInfo (`src/server/k8s-client.ts`)