thoth-agents 0.1.0

package/dist/utils/tmux-session-manager.d.ts

@@ -0,0 +1,63 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { TmuxConfig } from '../config/schema';
+/**
+ * Event shape for session events
+ */
+interface SessionEvent {
+    type: string;
+    properties?: {
+        info?: {
+            id?: string;
+            parentID?: string;
+            title?: string;
+        };
+        sessionID?: string;
+        status?: {
+            type: string;
+        };
+    };
+}
+/**
+ * TmuxSessionManager tracks child sessions and spawns/closes tmux panes for them.
+ *
+ * Uses session.status events for completion detection instead of polling.
+ */
+export declare class TmuxSessionManager {
+    private client;
+    private tmuxConfig;
+    private serverUrl;
+    private sessions;
+    private pollInterval?;
+    private enabled;
+    constructor(ctx: PluginInput, tmuxConfig: TmuxConfig);
+    /**
+     * Handle session.created events.
+     * Spawns a tmux pane for child sessions (those with parentID).
+     */
+    onSessionCreated(event: SessionEvent): Promise<void>;
+    /**
+     * Handle session.status events for completion detection.
+     * Uses session.status instead of deprecated session.idle.
+     *
+     * When a session becomes idle (completed), close its pane.
+     */
+    onSessionStatus(event: SessionEvent): Promise<void>;
+    /**
+     * Handle session.deleted events.
+     * When a session is deleted, close its tmux pane immediately.
+     */
+    onSessionDeleted(event: SessionEvent): Promise<void>;
+    private startPolling;
+    private stopPolling;
+    /**
+     * Poll sessions for status updates (fallback for reliability).
+     * Also handles timeout and missing session detection.
+     */
+    private pollSessions;
+    private closeSession;
+    /**
+     * Clean up all tracked sessions.
+     */
+    cleanup(): Promise<void>;
+}
+export {};

package/dist/utils/tmux.d.ts

@@ -0,0 +1,32 @@
+import type { TmuxConfig } from '../config/schema';
+/**
+ * Reset the server availability cache (useful when server might have started)
+ */
+export declare function resetServerCheck(): void;
+/**
+ * Get cached tmux path, initializing if needed
+ */
+export declare function getTmuxPath(): Promise<string | null>;
+/**
+ * Check if we're running inside tmux
+ */
+export declare function isInsideTmux(): boolean;
+export interface SpawnPaneResult {
+    success: boolean;
+    paneId?: string;
+}
+/**
+ * Spawn a new tmux pane running `opencode attach <serverUrl> --session <sessionId>`
+ * This connects the new TUI to the existing server so it receives streaming updates.
+ * After spawning, applies the configured layout to auto-rebalance all panes.
+ * Returns the pane ID so it can be closed later.
+ */
+export declare function spawnTmuxPane(sessionId: string, description: string, config: TmuxConfig, serverUrl: string): Promise<SpawnPaneResult>;
+/**
+ * Close a tmux pane by its ID and reapply layout to rebalance remaining panes
+ */
+export declare function closeTmuxPane(paneId: string): Promise<boolean>;
+/**
+ * Start background check for tmux availability
+ */
+export declare function startTmuxCheck(): void;

package/dist/utils/zip-extractor.d.ts

@@ -0,0 +1 @@
+export declare function extractZip(archivePath: string, destDir: string): Promise<void>;

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "thoth-agents",
+  "version": "0.1.0",
+  "description": "Delegate-first OpenCode plugin with seven agents, thoth-mem persistence, and bundled SDD skills.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "thoth-agents": "./dist/cli/index.js"
+  },
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "ai",
+    "agents",
+    "orchestration",
+    "llm",
+    "claude",
+    "gpt",
+    "gemini"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EremesNG/thoth-agents"
+  },
+  "bugs": {
+    "url": "https://github.com/EremesNG/thoth-agents/issues"
+  },
+  "homepage": "https://github.com/EremesNG/thoth-agents#readme",
+  "files": [
+    "dist",
+    "src/skills",
+    "src/skills/_shared",
+    "thoth-agents.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@ast-grep/cli": "^0.40.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@opencode-ai/plugin": "1.4.7",
+    "@opencode-ai/sdk": "1.4.7",
+    "unique-names-generator": "^4.7.1",
+    "vscode-jsonrpc": "^8.2.0",
+    "vscode-languageserver-protocol": "^3.17.5",
+    "which": "^6.0.0",
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.2",
+    "@types/node": "^22.19.19",
+    "@types/which": "^3.0.4",
+    "tsup": "^8.5.1",
+    "tsx": "4.22.2",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.6"
+  },
+  "overrides": {
+    "hono": "4.12.19",
+    "postcss": "8.5.14",
+    "tsx": "4.22.2"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly && pnpm run generate-schema",
+    "generate-schema": "tsx scripts/generate-schema.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "biome lint .",
+    "format": "biome format . --write",
+    "check": "biome check --write .",
+    "check:ci": "biome check .",
+    "dev": "pnpm run build && opencode",
+    "release:patch": "npm version patch && git push --follow-tags && npm publish",
+    "release:minor": "npm version minor && git push --follow-tags && npm publish",
+    "release:major": "npm version major && git push --follow-tags && npm publish"
+  }
+}

package/src/skills/_shared/openspec-convention.md

@@ -0,0 +1,131 @@
+# OpenSpec Convention
+
+## Harness Scope
+
+OpenSpec artifacts are harness-independent filesystem artifacts. The canonical
+`openspec/` paths, filenames, and archive layout do not change across adapter
+bindings.
+
+This file defines harness-neutral artifact semantics. Any runtime-specific file
+read/write, delegation, or blocking user input surface is an adapter binding
+and must preserve the canonical behavior described here. If a runtime lacks a
+required primitive, treat it as an unsupported-capability and report the
+limitation instead of changing artifact semantics.
+
+## Mode Scope
+
+This convention applies only when the artifact store mode includes OpenSpec:
+`openspec` and `hybrid`.
+
+- In `thoth-mem` mode, skip canonical `openspec/` file writes.
+- In `thoth-mem` mode, skip filesystem artifact recovery.
+
+## Pre-flight Validation
+
+When the selected persistence mode includes OpenSpec (`openspec` or `hybrid`),
+every SDD skill must verify this structure before proceeding:
+
+1. `openspec/config.yaml` exists
+2. `openspec/specs/` exists
+3. `openspec/changes/` exists
+
+If any required item is missing:
+
+- STOP and inform the orchestrator that `openspec/` is not initialized.
+- Recommend running the `sdd-init` skill first.
+- Do NOT attempt to create the structure in that skill.
+
+If all required items exist, continue normally.
+
+## Directory Structure
+
+```text
+openspec/
+├── config.yaml
+├── specs/
+│   └── {domain}/spec.md
+└── changes/
+    ├── archive/
+    └── {change-name}/
+        ├── proposal.md
+        ├── specs/
+        │   └── {domain}/spec.md
+        ├── design.md
+        ├── tasks.md
+        └── verify-report.md
+```
+
+## Canonical Artifacts
+
+| Artifact | Canonical path | Notes |
+| --- | --- | --- |
+| Proposal | `openspec/changes/{change-name}/proposal.md` | Intent, scope, approach |
+| Delta specs | `openspec/changes/{change-name}/specs/{domain}/spec.md` | Use one file per domain |
+| Main specs | `openspec/specs/{domain}/spec.md` | Source of truth after archive |
+| Design | `openspec/changes/{change-name}/design.md` | Architecture and file plan |
+| Tasks | `openspec/changes/{change-name}/tasks.md` | Checkbox checklist updated by apply |
+| Verify report | `openspec/changes/{change-name}/verify-report.md` | Compliance matrix and evidence |
+
+`apply-progress` and `archive-report` are durable SDD artifacts, but they are
+primarily persisted through thoth-mem topic keys when the mode includes
+thoth-mem.
+
+The canonical OpenSpec copy is the filesystem representation of these artifacts
+for `openspec` and `hybrid` modes. thoth-mem topic keys are the memory
+representation when the mode includes thoth-mem; neither representation changes
+the harness-neutral artifact names or lifecycle.
+
+## Writing Rules
+
+- Preserve canonical filenames and locations.
+- Read an existing artifact before rewriting it.
+- Keep change-specific artifacts under
+  `openspec/changes/{change-name}/...`.
+- Keep long-lived specs under `openspec/specs/{domain}/spec.md`.
+- Archive completed changes under
+  `openspec/changes/archive/YYYY-MM-DD-{change-name}/`.
+
+## Artifact Content Rules
+
+- `proposal.md` explains why the change exists.
+- `spec.md` uses RFC 2119 keywords and Given/When/Then scenarios (full pipeline only).
+- `design.md` explains how the change will be implemented (full pipeline only).
+- `tasks.md` is phase-based and uses Markdown checkboxes.
+- `verify-report.md` maps acceptance criteria to executed evidence: spec
+  scenarios in full pipeline, proposal success criteria in accelerated pipeline.
+
+Progress tracking surfaces may mirror task status for user visibility, but
+`tasks.md` remains the canonical OpenSpec task artifact whenever the selected
+persistence mode includes OpenSpec.
+
+## `config.yaml` Shape
+
+```yaml
+schema: spec-driven
+
+context: |
+  Project background, stack, and constraints.
+
+rules:
+  proposal:
+    - Proposal-specific guidance
+  specs:
+    - Require RFC 2119 keywords
+    - Require Given/When/Then scenarios
+  design:
+    - Document architecture decisions with rationale
+  tasks:
+    - Use phased checklists with hierarchical numbering
+  apply:
+    - Match repository conventions
+    tdd: false
+    test_command: ''
+  verify:
+    test_command: ''
+    build_command: ''
+    coverage_threshold: 0
+  archive:
+    - Warn before destructive merges
+```
+
+Treat `rules` entries as mandatory phase-specific constraints whenever present.

package/src/skills/_shared/persistence-contract.md

@@ -0,0 +1,162 @@
+# Persistence Contract
+
+## Supported Persistence Modes
+
+| Mode | Read order | Write targets | Use when |
+| --- | --- | --- | --- |
+| `thoth-mem` | thoth-mem only | thoth-mem only | The user wants no repo artifact changes |
+| `openspec` | filesystem only | OpenSpec files only | The user wants visible repo artifacts without memory overhead |
+| `hybrid` | thoth-mem, then filesystem fallback | thoth-mem and OpenSpec files | The change should survive compaction and exist in the repo |
+| `none` | orchestrator prompt context only | nowhere (inline response only) | Ephemeral exploration, privacy-sensitive work, or no persistence backend available |
+
+SDD skills MUST obey the selected artifact store mode. Do not reference or rely
+on engram.
+
+## Mode Rules
+
+### `thoth-mem`
+
+1. Read SDD artifacts from thoth-mem only.
+2. Write SDD artifacts to thoth-mem only.
+3. Do not create or modify canonical `openspec/` artifacts.
+
+### `openspec`
+
+1. Read SDD artifacts from canonical OpenSpec paths only.
+2. Write SDD artifacts to canonical OpenSpec paths only.
+3. Do not call thoth-mem save or recovery tools.
+
+### `none`
+
+1. Read SDD artifacts from orchestrator prompt context only.
+2. Do not persist artifacts to any external store.
+3. Return all artifacts as inline text in the response.
+4. Do not call thoth-mem save tools.
+5. Do not create or modify OpenSpec files.
+6. Recommend enabling `thoth-mem` or `openspec` for persistent work.
+
+## Hybrid Rules
+
+When running in `hybrid` mode:
+
+1. Write the canonical OpenSpec artifact to the filesystem.
+2. Persist the same full artifact to thoth-mem with a deterministic `topic_key`.
+3. Treat the operation as complete only when both writes succeed.
+4. If filesystem and memory diverge, repair them immediately by rewriting the
+   stale copy from the freshest full artifact.
+
+## Memory Ownership
+
+Memory responsibilities are split by semantic role between orchestrator and
+sub-agents:
+
+**Orchestrator owns general memory:**
+- Decisions, discoveries, bug fixes, session summaries
+- Progress checkpoints (SDD task state updates)
+- User preferences and configuration notes
+
+**Sub-agents write deterministic SDD artifacts:**
+- Canonical SDD artifacts with topic_key matching `sdd/{change}/{artifact}`
+- Includes: proposal, spec, design, tasks, apply-progress, verify-report,
+  archive-report, state
+- Sub-agents persist these directly when the active mode includes thoth-mem
+- Sub-agents do NOT write general memory observations
+
+This split preserves artifact nuance (sub-agents have full context when writing)
+while keeping general memory centralized under orchestrator control. In
+harnesses that cannot hard-enforce the split, treat it as instruction-level
+governance and disclose any unsupported-capability that prevents compliance.
+
+## Retrieval Protocol
+
+### 3-Layer Recall for thoth-mem and hybrid modes
+
+Always complete the full 3-layer recall before using content as source material:
+
+1. **Layer 1 (Compact Index):** call the memory tool binding for `mem_search`
+   with compact mode to scan observation IDs and titles. This is the most
+   token-efficient entry point.
+2. **Layer 2 (Timeline Context):** call the memory tool binding for
+   `mem_timeline` to retrieve chronological context (before/after
+   observations) to disambiguate or verify the correct artifact.
+3. **Layer 3 (Full Body):** call the memory tool binding for
+   `mem_get_observation` to retrieve the complete artifact body for use as
+   source material.
+
+**Mode guidance:**
+- Use `mode: "compact"` (default) for most queries; it returns only IDs and
+  titles.
+- Use `mode: "preview"` only when compact results are insufficient to
+  disambiguate between multiple candidates.
+
+**Never treat `mem_search` output—compact or preview—as the artifact body.**
+Always complete the 3-layer recall before using content as source material.
+
+### Mode-specific retrieval
+
+1. If the mode is `thoth-mem`, apply the 3-layer recall with the exact SDD
+   topic key.
+2. If the mode is `openspec`, read the canonical OpenSpec path from the
+   filesystem only.
+3. If the mode is `hybrid`, apply the 3-layer recall with the exact SDD topic
+   key.
+4. In `hybrid`, if nothing is found in thoth-mem, read the canonical OpenSpec
+   path from the filesystem.
+5. In `hybrid`, if filesystem recovery succeeds, re-save the artifact to
+   thoth-mem so the two stores converge again.
+6. If the mode is `none`, read artifacts from the orchestrator prompt context
+   only. Do not attempt to retrieve from thoth-mem or filesystem.
+
+## Artifact Ownership
+
+- `sdd-propose` persists `sdd/{change-name}/proposal`
+- `sdd-spec` persists `sdd/{change-name}/spec`
+- `sdd-design` persists `sdd/{change-name}/design`
+- `sdd-tasks` persists `sdd/{change-name}/tasks`
+- `sdd-apply` persists `sdd/{change-name}/apply-progress` and re-persists
+  updated `sdd/{change-name}/tasks`
+- `sdd-verify` persists `sdd/{change-name}/verify-report`
+- `sdd-archive` persists `sdd/{change-name}/archive-report`
+- `state` persists `sdd/{change-name}/state`
+
+## Governance Placement
+
+- The artifact governance validator is **report-only**.
+- It runs after `sdd-tasks` produces the canonical checklist and before any
+  future `sdd-apply` entrypoint consumes the report.
+- It does **not** replace `plan-reviewer` or `executing-plans`.
+- It does **not** mark task state, enforce execution, or alter review gating.
+- Root-session memory and progress checkpoints remain orchestrator-owned;
+  sub-agents may surface governance findings, but they must stay within the
+  active artifact store mode and delegate-first boundaries.
+
+## Pipeline Type Impact on Prerequisites
+
+The orchestrator passes `pipeline-type` (`accelerated` or `full`) alongside the
+persistence mode. This affects which artifacts each skill requires:
+
+| Artifact | Full pipeline | Accelerated pipeline |
+| --- | --- | --- |
+| Proposal | Required by all phases | Required by all phases (serves as acceptance reference) |
+| Spec | Required by design, tasks, apply, verify, archive | Not produced; not required |
+| Design | Required by tasks, apply, verify, archive | Not produced; not required |
+| Tasks | Required by apply, verify, archive | Required by apply, verify, archive |
+| Verify report | Required by archive | Required by archive |
+
+In accelerated pipeline, the proposal serves as the acceptance reference where
+specs would normally be used. Skills must adapt their retrieval, compliance
+checks, and archive behavior accordingly.
+
+## Recovery Notes
+
+- Prefer exact topic-key queries over fuzzy natural-language search.
+- Always use the 3-layer recall (`mem_search` → `mem_timeline` →
+  `mem_get_observation`) before treating an artifact as source material.
+- If multiple observations match in `mem_search`, use `mem_timeline` to inspect
+  chronological context and disambiguate.
+- In `openspec` mode, repair missing or stale artifacts by rewriting the
+  canonical OpenSpec file only.
+- In `thoth-mem` mode, repair missing or stale artifacts by re-saving the full
+  artifact to thoth-mem only.
+- In `hybrid` mode, use the filesystem copy only as fallback or repair input,
+  then converge both stores.

package/src/skills/_shared/thoth-mem-convention.md

@@ -0,0 +1,124 @@
+# thoth-mem Convention
+
+## Harness Scope
+
+This convention defines harness-neutral thoth-mem semantics for SDD artifacts.
+Tool names are adapter bindings, not universal semantics. Use the thoth-mem
+operation names (`mem_search`, `mem_timeline`, `mem_get_observation`,
+`mem_save`, `mem_update`) as the portable vocabulary and map them to the
+callable tool names exposed by the active binding surface.
+
+If a needed thoth-mem operation is not available, treat it as an
+unsupported-capability, disclose the limitation, and do not pretend
+persistence or recovery succeeded.
+
+Governance that a harness cannot hard-enforce remains instruction-level:
+semantic role ownership, parent session/project scoping, prompt-save
+prohibitions, and SDD topic-key namespace protection still apply.
+
+## Mode Scope
+
+This convention applies only when the artifact store mode includes thoth-mem:
+`thoth-mem` and `hybrid`.
+
+- In `openspec` mode, skip thoth-mem saves.
+- In `openspec` mode, skip thoth-mem recovery and use filesystem artifacts
+  instead.
+
+## Tool Names
+
+Use the thoth-mem operation names through the active binding surface. Prefer
+the callable names actually exposed by the runtime.
+
+## Topic Key Format
+
+All SDD artifacts use this deterministic pattern:
+
+```text
+sdd/{change-name}/{artifact}
+```
+
+Supported artifact names:
+
+- `proposal`
+- `spec`
+- `design`
+- `design-brief`
+- `tasks`
+- `apply-progress`
+- `verify-report`
+- `archive-report`
+- `state`
+
+Use the same value for `title` and `topic_key` unless there is a strong reason
+not to.
+
+## State Artifact Format
+
+The orchestrator semantic role persists a lightweight state checkpoint after
+each SDD phase transition to enable recovery:
+
+```yaml
+change: {change-name}
+phase: {last-completed-phase}
+mode: {thoth-mem|openspec|hybrid|none}
+pipeline: {accelerated|full}
+artifacts:
+  proposal: true
+  spec: false       # always false in accelerated pipeline
+  design: false     # always false in accelerated pipeline
+  tasks: false
+  apply-progress: false
+  verify-report: false
+  archive-report: false
+last_updated: {ISO 8601 timestamp}
+```
+
+Save with the memory tool binding for `mem_save`, using the canonical SDD
+topic key and the required metadata fields:
+`title`, `topic_key`, `type`, `project`, `scope`, and `content`.
+
+Recovery: `mem_search("sdd/{change-name}/state")` using the active binding
+surface → `mem_timeline(id)` when needed for chronology →
+`mem_get_observation(id)` → parse YAML → restore phase state.
+
+## Three-Layer Recall Protocol
+
+1. **Scan compact index** by exact topic key:
+
+Use the memory tool binding for `mem_search` with
+`query: "topic_key:sdd/{change-name}/{artifact}"`, `project`, and
+`mode: "compact"`.
+
+Use `mode: "compact"` (the default) for token efficiency. Switch to `mode: "preview"`
+only when compact results are insufficient to disambiguate between multiple results.
+
+2. **Get chronological context** around the found observation:
+
+Use the memory tool binding for `mem_timeline` with `observation_id`,
+`before`, and `after`.
+
+This shows related observations in the same session, helping you understand the
+artifact's evolution and dependencies.
+
+3. **Retrieve full artifact content**:
+
+Use the memory tool binding for `mem_get_observation` with the observation ID.
+
+Search returns compact results (IDs + titles) by default. Neither compact nor
+preview mode returns the full artifact body. Always complete the 3-layer recall
+to get the actual content.
+
+## Save Contract
+
+**CRITICAL:** The orchestrator MUST persist the state artifact after each SDD
+phase transition. This is the canonical checkpoint for resume/recovery.
+
+Persist SDD artifacts with a stable topic key so repeated saves upsert instead
+of creating duplicates:
+
+Use the memory tool binding for `mem_save` with the canonical SDD topic key
+and the full artifact markdown in `content`.
+
+For `sdd-apply`, save the progress report under `apply-progress` and re-save the
+updated task list under `tasks` after checkboxes change.