@pellux/goodvibes-agent 0.1.0

package/.goodvibes/GOODVIBES.md

@@ -0,0 +1,35 @@
+## GoodVibes Agent Operating Policy
+
+GoodVibes Agent is a proactive personal operator assistant built on the GoodVibes TUI shell foundation. Its default work happens serially in the main conversation.
+
+## Default Behavior
+
+- Work in the main conversation by default.
+- Take safe, non-destructive actions proactively when the user asks for an outcome.
+- Use read-only daemon/operator routes, local Agent memory, local skills, local personas, and Agent knowledge when they help the task.
+- Ask before destructive, externally visible, costly, privacy-sensitive, service-changing, package-installing, or broad filesystem/network actions unless the user explicitly commanded that exact action.
+- Keep normal assistant chat separate from shared build/delegation sessions.
+
+## Background Agents And WRFC
+
+- Do not use background agents as a default execution strategy.
+- Do not fan out Engineer, Reviewer, Tester, Verifier, or similar local roots from Agent.
+- WRFC is never the default reasoning path.
+- Request WRFC only when the user explicitly asks to build, implement, fix, patch, or review code, or explicitly says to use WRFC/agent review.
+- For explicit build/fix/review work, delegate one request to GoodVibes TUI through the public shared-session/build-delegation contract with the full original user ask.
+- If no stable public delegation route is available, report the missing route instead of pretending to implement locally.
+
+## Product Boundaries
+
+- Agent connects to an already-running GoodVibes daemon. It does not start, restart, install, or own daemon/listener services.
+- GoodVibes TUI owns coding execution, file edits, git/worktree lifecycle, sandbox/QEMU UX, and WRFC owner chains.
+- Agent owns personal operator flow, setup/config surfaces, local memory, local skills, local personas, Agent knowledge, status/approval/automation observability, and explicit delegation receipts.
+
+## Engineering Rules
+
+- Use Bun.
+- Author code in TypeScript only.
+- Do not add explicit `any`.
+- Do not add runtime imports from `goodvibes-tui/src/*`.
+- Prefer public `@pellux/goodvibes-sdk` contracts and daemon routes.
+- Keep copied TUI bones deliberate and document promotion candidates for shared packages.

package/.goodvibes/agents/reviewer.md

@@ -0,0 +1,48 @@
+---
+name: reviewer
+description: Serial review of GoodVibes Agent changes against product policy, release gates, and TypeScript quality
+tools: [read, find, analyze]
+---
+
+You review GoodVibes Agent work. Your job is to identify concrete defects, product-boundary violations, and release risks. You verify claims by inspecting files and cite exact paths.
+
+## Review Priorities
+
+1. Agent policy: main-conversation serial behavior by default; no hidden local agent fanout; no default WRFC.
+2. Product boundary: Agent connects to the external daemon; it does not start, restart, install, or own daemon/listener services.
+3. Delegation boundary: build/fix/review code work is explicitly delegated to GoodVibes TUI through public contracts.
+4. TypeScript quality: Bun-first TypeScript only, no explicit `any`, no authored JavaScript variants.
+5. SDK boundary: public `@pellux/goodvibes-sdk` imports and daemon/operator routes only; no runtime imports from `goodvibes-tui/src/*`.
+6. Packaging: `goodvibes-agent` bin, Agent package identity, Agent docs, and no copied TUI-only package-facing guidance.
+
+## Review Process
+
+1. Read the completion report or changed-file list.
+2. Inspect the files that define the behavior under review.
+3. Check tests and release gates that should cover the change.
+4. Report findings first, ordered by severity.
+5. Keep summaries brief and secondary.
+
+## Output Format
+
+Use this structure:
+
+```text
+Findings
+- severity: file:line - issue and impact
+
+Open Questions
+- question or assumption, if any
+
+Validation Notes
+- tests/gates reviewed or missing
+```
+
+If there are no findings, say so clearly and list residual risk or missing validation.
+
+## What You Do Not Do
+
+- Do not modify code.
+- Do not spawn other agents.
+- Do not broaden scope beyond the reviewed slice.
+- Do not treat copied coding-TUI behavior as acceptable unless it is blocked, externalized, or explicitly delegated.

package/.goodvibes/skills/add-provider/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: add-provider
+description: Adds custom LLM providers and models to GoodVibes Agent. Use when the user wants to add a provider, add a model, configure Ollama, Together AI, OpenRouter, Groq, LM Studio, Fireworks, vLLM, or any OpenAI-compatible endpoint.
+version: 1.0.0
+triggers:
+  - /add-provider
+  - add provider
+  - add a provider
+  - new provider
+  - custom provider
+  - add model
+  - add a model
+author: goodvibes
+---
+
+# Add Custom Provider
+
+Interactively collect provider and model details from the user, then write a JSON config to `~/.goodvibes/agent/providers/{name}.json`.
+
+## Workflow
+
+### Step 1: Check for Existing Provider
+
+Before collecting info, check if `~/.goodvibes/agent/providers/` already has JSON files. If the user names a provider that already exists, ask:
+- **Add models** to the existing provider, or
+- **Overwrite** it entirely
+
+If adding models, read the existing JSON, append new models, and write back.
+
+### Step 2: Collect Provider Details
+
+Ask the user for each field. Apply smart defaults when the provider name matches a known service.
+
+#### Required Fields
+
+| Field | Description | Validation |
+|-------|-------------|------------|
+| `name` | Internal ID | Lowercase alphanumeric + hyphens only, 1-64 chars |
+| `displayName` | Human-readable name | Non-empty string |
+| `type` | API compatibility | `openai-compat` (recommended) or `anthropic-compat` (not yet supported — use `openai-compat`) |
+| `baseURL` | API endpoint | Must start with `http://` or `https://` |
+
+> **Note:** `anthropic-compat` is accepted in the JSON schema for forward compatibility but is not yet functional at runtime. The loader will skip configs with this type and emit a warning. Use `openai-compat` for now — most Anthropic-compatible proxies (e.g., via LiteLLM) expose an OpenAI-compatible endpoint.
+
+#### Optional Fields
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `apiKeyEnv` | Environment variable for API key | None |
+| `apiKey` | Explicit API key (not recommended) | None |
+| `defaultHeaders` | Custom HTTP headers sent with every API request (e.g., for proxy authentication or routing) | None |
+
+### Smart Defaults
+
+When the user mentions a known provider, pre-fill these values and confirm:
+
+```yaml
+ollama:
+  displayName: Ollama
+  type: openai-compat
+  baseURL: http://localhost:11434/v1
+  apiKeyEnv: null
+
+together:
+  displayName: Together AI
+  type: openai-compat
+  baseURL: https://api.together.xyz/v1
+  apiKeyEnv: TOGETHER_API_KEY
+
+openrouter:
+  displayName: OpenRouter
+  type: openai-compat
+  baseURL: https://openrouter.ai/api/v1
+  apiKeyEnv: OPENROUTER_API_KEY
+
+groq:
+  displayName: Groq
+  type: openai-compat
+  baseURL: https://api.groq.com/openai/v1
+  apiKeyEnv: GROQ_API_KEY
+
+lm-studio:
+  displayName: LM Studio
+  type: openai-compat
+  baseURL: http://localhost:1234/v1
+  apiKeyEnv: null
+
+fireworks:
+  displayName: Fireworks AI
+  type: openai-compat
+  baseURL: https://api.fireworks.ai/inference/v1
+  apiKeyEnv: FIREWORKS_API_KEY
+
+vllm:
+  displayName: vLLM
+  type: openai-compat
+  baseURL: http://localhost:8000/v1
+  apiKeyEnv: null
+```
+
+If the name does not match a known provider, ask for all fields individually.
+
+### Step 3: Collect Model Details
+
+Collect at least one model. For each model:
+
+| Field | Description | Validation |
+|-------|-------------|------------|
+| `id` | Model identifier sent to the API | Non-empty string |
+| `displayName` | Human-readable name | Non-empty string |
+| `description` | Short description | Optional, auto-generate if blank |
+| `contextWindow` | Max tokens in context | Positive integer |
+| `capabilities.toolCalling` | Supports function/tool calling | Boolean, default `true` |
+| `capabilities.codeEditing` | Good at code editing tasks | Boolean, default `true` |
+| `capabilities.reasoning` | Extended reasoning/chain-of-thought | Boolean, default `false` |
+| `capabilities.multimodal` | Supports image input | Boolean, default `false` |
+| `reasoningEffort` | Supported reasoning effort levels | Optional, e.g., `["low", "medium", "high"]` |
+
+After each model, ask: "Add another model?" Loop until done.
+
+### Step 4: Preview and Confirm
+
+Show the complete JSON to the user and ask for confirmation before writing.
+
+Example output:
+
+```json
+{
+  "name": "ollama",
+  "displayName": "Ollama",
+  "type": "openai-compat",
+  "baseURL": "http://localhost:11434/v1",
+  "models": [
+    {
+      "id": "llama3.3-70b",
+      "displayName": "Llama 3.3 70B",
+      "description": "Meta's Llama 3.3 70B parameter model",
+      "contextWindow": 131072,
+      "capabilities": {
+        "toolCalling": true,
+        "codeEditing": true,
+        "reasoning": true,
+        "multimodal": false
+      },
+      "reasoningEffort": ["low", "medium", "high"]
+    }
+  ]
+}
+```
+
+### Step 5: Write the File
+
+Write to `~/.goodvibes/agent/providers/{name}.json`. Create the directory if it does not exist.
+
+Use `precision_write` with `mode: "fail_if_exists"` for new providers. Use `mode: "overwrite"` when the user chose to overwrite an existing provider or when merging models into an existing file.
+
+If the `apiKeyEnv` field is set, include it in the JSON. If the user provided an explicit `apiKey`, include it but warn that storing keys in plain text is not recommended -- suggest using an environment variable instead.
+
+If `defaultHeaders` were provided, include them.
+
+### Step 6: Confirm
+
+Tell the user:
+- The file was written to `~/.goodvibes/agent/providers/{name}.json`
+- The provider should be available to the Agent runtime after provider reload or next Agent startup
+- If an API key is needed, remind them to set the environment variable
+
+## Validation Rules
+
+Before writing, verify:
+1. `name` matches `/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/` and is 1-64 characters (no trailing hyphens)
+2. `baseURL` starts with `http://` or `https://`
+3. `contextWindow` is a positive integer for every model
+4. At least one model is defined
+5. Every model has a non-empty `id` and `displayName`
+
+If validation fails, tell the user which field is invalid and ask for correction.
+
+## JSON Schema Reference
+
+The provider JSON maps to the codebase types:
+
+- Provider registration uses `OpenAICompatProvider` for `openai-compat` type. The `anthropic-compat` type is parsed and accepted in the JSON but is **not yet supported at runtime** — the loader skips it with a warning. Recommend `openai-compat` for all custom providers.
+- `OpenAICompatOptions`: `{ name, baseURL, apiKey, defaultModel, models }`
+- Model entries map to `ModelDefinition`: `{ id, provider, displayName, description, contextWindow, capabilities, reasoningEffort?, selectable }`
+  - `reasoningEffort?: string[]` — optional array of supported effort levels, e.g., `["low", "medium", "high"]`
+- The `selectable` field defaults to `true` for custom models
+- The `provider` field in `ModelDefinition` is auto-set to the provider `name`
+
+## Conversational Style
+
+Be natural and helpful. Guide users step-by-step but do not be overly verbose. If the user provides multiple details at once (e.g., "add ollama with llama3.3-70b"), extract what you can and only ask for missing fields.
+
+## Edge Cases
+
+- **Unknown context window**: Suggest 4096 as a safe default, note the user can update later
+- **No API key needed**: Omit `apiKeyEnv` and `apiKey` from the JSON entirely
+- **User provides a full JSON blob**: Validate it against the schema and write directly
+- **Multiple providers in one session**: After completing one, ask if they want to add another

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to GoodVibes Agent will be recorded here.
+
+## 0.1.0 - 2026-05-28
+
+- Published the first public alpha package for `@pellux/goodvibes-agent`.
+- Kept the near-fork GoodVibes TUI shell, renderer, input, fullscreen workspace, command registry, and release foundation.
+- Preserved Agent product policy: serial/proactive main conversation by default, no local Agent-owned WRFC/spawn fanout, and explicit GoodVibes TUI delegation for build/fix/review work.
+- Moved Agent-owned runtime state to `.goodvibes/agent` surface roots.
+- Updated packaged Agent guidance, reviewer persona, and provider skill to avoid copied TUI WRFC/multi-agent defaults.
+- Kept daemon lifecycle external: Agent connects to an already-running GoodVibes daemon and blocks daemon/service ownership commands.
+- Pinned `@pellux/goodvibes-sdk` to `0.33.35`.
+
+## 0.0.0 - Private Baseline
+
+- Copied the GoodVibes terminal foundation as a near-fork starting point for the Agent product.
+- Renamed package identity to `@pellux/goodvibes-agent` and exposed one executable, `goodvibes-agent`.
+- Pinned `@pellux/goodvibes-sdk` to `0.33.35`.
+- Removed packaged daemon binaries and blocked Agent-owned daemon/service lifecycle commands.
+- Limited package-facing docs to Agent install, external-daemon deployment, and release guidance.
+- Replaced copied coding-first orchestration policy with Agent serial/proactive policy and explicit GoodVibes TUI build delegation.
+- Added the first Agent operator workspace on the copied fullscreen workspace foundation, exposed through `/agent`, `/home`, and `/operator`.
+
+The private baseline intentionally kept broad TUI foundation code so the Agent could inherit the renderer, input, fullscreen workspace, command registry, and release bones before Agent-specific policy was applied.

package/README.md

@@ -0,0 +1,74 @@
+# GoodVibes Agent
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#install)
+
+GoodVibes Agent is the personal operator assistant built on the GoodVibes terminal UI foundation. This repository is intentionally in a near-fork baseline phase: the shell, renderer, input, fullscreen workspace, command, and release bones are copied from the terminal product first, then the coding-specific behavior is removed or reshaped deliberately.
+
+The Agent product connects to an already-running GoodVibes daemon. It does not install, start, stop, restart, or own the daemon, HTTP listener, web surface, or service lifecycle.
+
+## Install
+
+Install the public alpha package with Bun:
+
+```sh
+bun add -g @pellux/goodvibes-agent
+goodvibes-agent --help
+goodvibes-agent status
+```
+
+If Bun reports untrusted lifecycle dependencies, trust only the package and dependencies required by this package:
+
+```sh
+bun pm trust -g @pellux/goodvibes-agent @pellux/goodvibes-sdk core-js tree-sitter-css tree-sitter-javascript tree-sitter-json tree-sitter-python tree-sitter-typescript
+```
+
+## Source Usage
+
+```sh
+git clone https://github.com/mgd34msu/goodvibes-agent.git
+cd goodvibes-agent
+bun install
+bun run dev
+```
+
+Useful checks:
+
+```sh
+bunx tsc --noEmit
+bun run build
+bun run package:install-check
+bun run publish:check
+```
+
+Inside the Agent TUI, use `/agent`, `/home`, or `/operator` to open the operator workspace. It is the Agent-first fullscreen surface for setup, status, knowledge, local memory/skills, work-plan/approval review, automation observability, and explicit build delegation to GoodVibes TUI.
+
+## Daemon Prerequisite
+
+Start or restart the daemon from GoodVibes TUI or the daemon host before launching Agent. Agent status and companion/knowledge routes connect to that external daemon, normally on `http://127.0.0.1:3421`.
+
+Agent intentionally blocks daemon lifecycle commands:
+
+```sh
+goodvibes-agent serve
+goodvibes-agent service start
+goodvibes-agent surfaces enable web
+```
+
+Those commands should return explicit external-daemon guidance instead of mutating local service posture.
+
+## Product Boundary
+
+GoodVibes Agent owns the operator assistant surface: serial assistant flow, proactive safe actions, local memory/skills/personas until stable shared registries exist, Agent knowledge routes, companion chat, approvals/automation observability, and explicit build delegation.
+
+GoodVibes TUI owns coding execution: file edits, git/worktree workflows, coding panels, sandbox/QEMU UX, and WRFC execution. Agent may delegate explicit build/fix/review work to TUI through public daemon/session contracts; normal assistant chat must not use shared coding sessions.
+
+## Package Docs
+
+Package-facing docs are intentionally narrow during the near-fork baseline:
+
+- [Getting Started](docs/getting-started.md)
+- [Deployment And Services](docs/deployment-and-services.md)
+- [Release And Publishing](docs/release-and-publishing.md)
+
+Broader TUI-derived reference docs may exist in the source tree while the near-fork foundation is being completed, but the package-facing Agent documentation is limited to the docs listed above.

package/bin/goodvibes-agent.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/main.ts';

package/docs/README.md

@@ -0,0 +1,23 @@
+# GoodVibes Agent Docs
+
+These are the package-facing docs for GoodVibes Agent.
+
+GoodVibes Agent is a near-fork of the GoodVibes terminal foundation with a different product brain. It uses the copied terminal shell, renderer, input, fullscreen workspace, command, and release bones while the Agent-specific assistant behavior is being rebuilt.
+
+Current package docs:
+
+- [Getting Started](getting-started.md)
+- [Deployment And Services](deployment-and-services.md)
+- [Release And Publishing](release-and-publishing.md)
+
+Important baseline constraints:
+
+- Agent installs one executable: `goodvibes-agent`.
+- Agent uses Bun and TypeScript-authored source.
+- Agent depends on `@pellux/goodvibes-sdk@0.33.35`.
+- Agent connects to an externally managed daemon.
+- Agent does not start, stop, restart, install, uninstall, or own daemon/listener/web/service lifecycle.
+- Normal assistant chat is not coding-session delegation.
+- Build/fix/review delegation to GoodVibes TUI must be explicit; WRFC is not the default Agent behavior.
+
+TUI-derived docs that remain outside this package-facing set are reference material during the near-fork foundation work. The Agent docs above define the supported alpha behavior.

package/docs/deployment-and-services.md

@@ -0,0 +1,57 @@
+# Deployment And Services
+
+GoodVibes Agent is a client/operator surface. It does not own daemon or listener deployment.
+
+## Service Ownership
+
+Agent must not:
+
+- start an embedded daemon
+- start an embedded HTTP listener
+- install or uninstall OS services
+- start, stop, or restart daemon services
+- enable web, listener, control-plane, or channel surface posture
+
+Those operations belong to GoodVibes TUI or the daemon host.
+
+## Agent Runtime
+
+The installed package exposes one executable:
+
+```sh
+goodvibes-agent
+```
+
+The executable is backed by TypeScript-authored source with a Bun shebang. Package install smoke must verify:
+
+- `goodvibes-agent --help`
+- `goodvibes-agent --version`
+- `goodvibes-agent status --json`
+- `goodvibes-agent smoke --json` when that command is available in the baseline being tested
+
+## External Daemon Connection
+
+Agent reads configuration and tokens, then connects to an already-running daemon. The default local control-plane URL is normally:
+
+```text
+http://127.0.0.1:3421
+```
+
+If the daemon is unavailable, unauthenticated, or on an incompatible SDK version, Agent commands should report actionable diagnostics without printing token values.
+
+## Surface Commands
+
+`goodvibes-agent surfaces`, `surfaces check`, and `surfaces show <surfaceId>` are read-only diagnostics.
+
+`surfaces enable` and `surfaces disable` are intentionally blocked in Agent because they can mutate daemon/listener/web/channel posture.
+
+## Release Rule
+
+Only publish Agent releases that preserve the Agent product policy:
+
+- serial/proactive assistant by default
+- local memory/skills/personas until shared registries are stable
+- Agent knowledge routes only for Agent wiki calls
+- companion chat for normal assistant chat
+- explicit delegation to GoodVibes TUI for build/fix/review work
+- WRFC only when explicitly requested for delegated build/fix/review work

package/docs/getting-started.md

@@ -0,0 +1,53 @@
+# Getting Started
+
+GoodVibes Agent `0.1.0` is the first public alpha of the personal operator assistant built on the GoodVibes TUI foundation.
+
+## Requirements
+
+- Bun `1.3.10` or newer
+- An already-running GoodVibes daemon compatible with `@pellux/goodvibes-sdk@0.33.35`
+- A daemon token/config path accepted by the external daemon
+
+Agent does not launch the daemon for you.
+
+## Install From Package
+
+```sh
+bun add -g @pellux/goodvibes-agent
+goodvibes-agent --help
+goodvibes-agent status
+```
+
+If Bun requires lifecycle trust:
+
+```sh
+bun pm trust -g @pellux/goodvibes-agent @pellux/goodvibes-sdk core-js tree-sitter-css tree-sitter-javascript tree-sitter-json tree-sitter-python tree-sitter-typescript
+```
+
+## Run From Source
+
+```sh
+git clone https://github.com/mgd34msu/goodvibes-agent.git
+cd goodvibes-agent
+bun install
+bun run dev
+```
+
+`bun run dev` starts the Agent TUI. The same entrypoint backs the installed `goodvibes-agent` command.
+
+Once the TUI opens, run `/agent`, `/home`, or `/operator` to open the Agent operator workspace. That fullscreen workspace is the current front door for setup/config, knowledge status, local memory and skills, read-only work/approval/automation views, and explicit GoodVibes TUI build delegation.
+
+## External Daemon
+
+Start the daemon from GoodVibes TUI or the daemon host before using daemon-backed Agent features. Agent expects the daemon to expose the public operator/Agent routes, including:
+
+- `/status`
+- `/api/goodvibes-agent/knowledge/status`
+- `/api/goodvibes-agent/knowledge/ask`
+- `/api/goodvibes-agent/knowledge/search`
+
+Agent lifecycle commands that would start or mutate daemon posture are blocked intentionally. Use `goodvibes-agent status`, `goodvibes-agent doctor`, and read-only surface checks for diagnostics.
+
+## Current Baseline Notes
+
+This repository keeps broad TUI-derived foundation code intentionally so Agent can use the mature terminal shell, renderer, input, fullscreen workspace, command registry, and release bones. The active Agent policy is serial/proactive by default, blocks local Agent-owned WRFC/spawn fanout, and delegates explicit build/fix/review work to GoodVibes TUI instead of turning the Agent into a coding TUI.

package/docs/release-and-publishing.md

@@ -0,0 +1,46 @@
+# Release And Publishing
+
+GoodVibes Agent `0.1.0` is the first public alpha release.
+
+## Package Identity
+
+- npm package: `@pellux/goodvibes-agent`
+- executable: `goodvibes-agent`
+- SDK dependency: exact pin to `@pellux/goodvibes-sdk@0.33.35`
+- runtime: Bun
+- source language: TypeScript
+- daemon ownership: external only
+
+## Required Gates
+
+Before any release candidate:
+
+```sh
+bun install
+bunx tsc --noEmit
+bun run build
+bun run package:install-check
+bun run publish:check
+npm pack --dry-run
+git diff --check
+```
+
+Also run the package install smoke from a packed artifact. It must prove:
+
+- the installed command is on `PATH`
+- the bin target is `bin/goodvibes-agent.ts`
+- the Bun shebang survives pack/install
+- `goodvibes-agent --help` works
+- `goodvibes-agent --version` reports the package version
+- daemon-backed commands fail clearly when the external daemon is unavailable or unauthenticated
+- no token value is printed
+
+## Do Not Ship
+
+Do not publish if package-facing docs or install commands refer to another package name, another executable, or Agent-owned daemon lifecycle.
+
+Do not ship daemon binaries from this package. If Agent later gets compiled artifacts, they must use Agent artifact names and remain separate from daemon ownership.
+
+## Near-Fork Baseline Rule
+
+The public alpha can include copied TUI foundation code, but package-facing behavior must follow Agent product policy. Follow-up work should continue pruning or reshaping copied coding-first surfaces while preserving the TUI-derived renderer, input, fullscreen workspace, command registry, and release bones.