@buehnenproduktionsgesellschaft/donna 0.1.0

package/LICENSE

@@ -0,0 +1,73 @@
+DONNA Code — Proprietary Software License
+
+Copyright (c) 2026 dbpg deutsche Bühnenproduktionsgesellschaft mbH & Co. KG.
+All rights reserved.
+
+1. Grant of Use
+
+Subject to the terms of this License and to a valid, paid subscription or
+account with dbpg where required, dbpg grants you a personal, non-exclusive,
+non-transferable, revocable license to install and use the DONNA Code
+software (the "Software") solely for the purpose of interacting with dbpg
+services through the Software's intended interfaces.
+
+2. Restrictions
+
+You may NOT, without prior written permission from dbpg:
+
+  (a) copy, modify, fork, redistribute, sublicense, sell, rent, lease, or
+      lend the Software or any portion thereof;
+  (b) reverse engineer, decompile, disassemble, or otherwise attempt to
+      derive the source code of the Software except to the extent such
+      activity is expressly permitted by applicable law;
+  (c) remove, alter, or obscure any proprietary notices in the Software;
+  (d) use the Software to build a competing product or service;
+  (e) circumvent any technical measures designed to control access to or
+      use of the Software or dbpg services;
+  (f) use the Software in any manner that violates applicable law.
+
+3. Ownership
+
+The Software is licensed, not sold. dbpg retains all right, title, and
+interest in and to the Software, including all intellectual property rights.
+No rights are granted to you other than those expressly stated in this
+License.
+
+4. Third-Party Components
+
+The Software incorporates third-party open-source components governed by
+their respective licenses. Such components remain subject to their original
+license terms; nothing in this License modifies those terms.
+
+5. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. dbpg DOES NOT WARRANT THAT
+THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE.
+
+6. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL dbpg
+BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE
+DAMAGES, OR ANY LOSS OF PROFITS OR REVENUE, ARISING OUT OF OR RELATED TO
+YOUR USE OF OR INABILITY TO USE THE SOFTWARE.
+
+7. Termination
+
+This License terminates automatically if you fail to comply with any of its
+terms. Upon termination, you must cease all use of the Software and remove
+all copies from your systems.
+
+8. Governing Law
+
+This License is governed by the laws of the Federal Republic of Germany,
+without regard to its conflict-of-law principles. Exclusive jurisdiction
+and venue lie with the competent courts at the registered seat of dbpg.
+
+9. Contact
+
+For licensing inquiries, please contact:
+  support@buehnenproduktionsgesellschaft.de
+
+dbpg deutsche Bühnenproduktionsgesellschaft mbH & Co. KG

package/README.md

@@ -0,0 +1,253 @@
+# DONNA Code
+
+A terminal-based AI coding assistant by [dbpg](https://dbpg.io).
+
+## Install
+
+```bash
+npm install -g @buehnenproduktionsgesellschaft/donna
+```
+
+## First-time setup
+
+```bash
+donna login                # paste your API key (validated against the gateway)
+donna login --browser      # also opens the portal page in your browser
+```
+
+Generate keys at https://centra.dbpg.io/dashboard.
+
+## Usage
+
+```bash
+# Start a new session
+donna
+
+# Start with a prompt
+donna "fix the bug in auth.ts"
+donna fix the bug          # quotes optional
+
+# Multi-line prompt from heredoc / pipe
+donna -p - <<'EOF'
+write a function that
+sums two numbers
+EOF
+echo "long prompt..." | donna -p -
+
+# Resume last session
+donna resume
+
+# Resume specific session
+donna resume abc123
+
+# Logout (remove API key from disk)
+donna logout
+```
+
+### Subcommands
+
+`login`, `logout`, and `resume` are reserved subcommand names. To use them as
+prompt text, pass them via `-p`:
+
+```bash
+donna -p login   # chat prompt: "login"
+```
+
+## Commands
+
+Type `/` in the TUI to see and filter all commands. `/help` lists them in-app.
+
+**Session & navigation**
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all commands and shortcuts |
+| `/clear` | Clear the chat |
+| `/resume [id]` | Resume the last (or a specific) session |
+| `/history` | Show past sessions |
+| `/exit` | Exit donna |
+
+**Conversation context**
+
+| Command | Description |
+|---------|-------------|
+| `/context` | Show context window usage and breakdown |
+| `/compact` | Compact the conversation into a summary |
+| `/inspect` | Browse past tool calls and compactions |
+
+**Workflows**
+
+| Command | Description |
+|---------|-------------|
+| `/init` | Analyze the project and create `DONNA.md` |
+| `/plan <goal>` | Create an implementation plan |
+| `/explain <file>` | Explain a file or concept |
+| `/review` | Review recent code changes |
+| `/security` | Full security audit of the project |
+| `/test [filter]` | Run tests and analyze failures |
+| `/diff` | Show the current git diff |
+| `/commit` | Generate a commit message and commit |
+| `/undo` | Undo the last file edit |
+| `/image <path>` | Analyze an image file |
+
+**Memory**
+
+| Command | Description |
+|---------|-------------|
+| `/memory` | Show or manage project memory |
+| `/clear-memory` | Clear all project memory |
+
+**Integrations**
+
+| Command | Description |
+|---------|-------------|
+| `/agents` | Show agent status and queue |
+| `/skills` | Enable / disable skills (Space toggles) |
+| `/mcp` | Enable / disable MCP servers (Space toggles); `/mcp restart <name>` |
+
+**Settings**
+
+| Command | Description |
+|---------|-------------|
+| `/model` | Show the current model |
+| `/thinking` | Set reasoning depth (none / low / medium / high) |
+| `/config` | Show configuration |
+
+**Account & permissions**
+
+| Command | Description |
+|---------|-------------|
+| `/account` | Show account and credits |
+| `/usage` | Show today's token usage |
+| `/login` | Show login status / how to re-authenticate |
+| `/logout` | Remove the API key from disk |
+| `/permissions` | Show saved permissions |
+| `/reset-permissions` | Reset all saved permissions |
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+O` | Expand/collapse tool outputs |
+| `Esc Esc` | Jump to previous message (revert) |
+| `Escape` | Clear input / cancel streaming / close modal |
+| `Alt+Enter` | Newline in input (also in `ask_user` note / `request_input`). On terminals that send a distinct Shift+Enter, that works too |
+| `Tab` | Accept suggestion / file path completion |
+| `Ctrl+C` | Quit |
+
+## Shortcuts
+
+| Prefix | Action |
+|--------|--------|
+| `!<cmd>` | Run `<cmd>` in your shell. Output is shown to you only — the model never sees it. Useful for quick lookups (`!ls`, `!git status`) without spending a model turn |
+
+## Tools
+
+DONNA Code has built-in tools that the AI uses automatically:
+
+- **read_file** — Read files with optional offset/limit
+- **edit_file** — Diff-based file editing (targeted string replacement)
+- **write_file** — Create new files
+- **glob** — Find files by pattern
+- **grep** — Search file contents by regex
+- **run_bash** — Execute shell commands
+- **web_search** — Search the web
+- **web_fetch** — Fetch full content from URLs
+- **todo_read / todo_write** — Mini-issue task list. Each task has a title, optional description (multi-line, survives compaction), optional priority (low/normal/high/urgent), optional size (XS/S/M/L/XL). `todo_read <id>` returns full detail so the assistant can pick a task up again after a context compaction
+- **ask_user** — Open a structured multi-choice modal for the user to answer
+- **request_input** — Prompt the user for free-text input (with optional masking for secrets)
+- **run_agent** — Delegate a focused sub-task to a sub-agent that runs in parallel
+
+## Project Context
+
+Create a `DONNA.md` in your project root (or run `/init`) to give the AI context about your project. This file is automatically loaded at the start of each session.
+
+Plans in `.plans/*.md` are also loaded automatically.
+
+## MCP Servers (optional)
+
+[MCP](https://modelcontextprotocol.io) lets you give DONNA extra tools beyond the
+built-ins — GitHub, Linear, databases, custom internal services. Note: for
+plain file access in the current project, the **built-in tools above are
+already enough**. MCP is for paths outside cwd or non-file integrations.
+
+Configure servers in either:
+- `~/.config/donna/mcp.json` (global, trusted automatically)
+- `.donna/mcp.json` (per-project, **requires explicit trust on first use**)
+
+```json
+{
+  "mcpServers": {
+    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
+  }
+}
+```
+
+### Workspace trust
+
+When DONNA finds a `.donna/mcp.json` in your current directory it has not
+seen before, you'll be prompted before any subprocess is started:
+
+```
+.donna/mcp.json declares the following MCP servers:
+  - github
+These run as subprocesses with full filesystem access.
+Trust this configuration? [y/N]
+```
+
+Answer `y` once and DONNA records the file's content hash in
+`~/.donna/config.json`. Subsequent runs are silent until the file changes.
+This protects you from a hostile cloned repository auto-running a
+subprocess on the first `donna` you type in that directory — the same
+threat model as VS Code's workspace trust.
+
+To revoke trust: edit `~/.donna/config.json` and remove the entry from
+`mcpTrust`, or delete the file entirely.
+
+## Configuration
+
+Config is stored in `~/.donna/config.json`. The API key is set by
+`donna login` — you generally don't edit this file by hand. Other fields:
+
+```json
+{
+  "endpoint": "https://api.centra.dbpg.io/v1",
+  "model": "donna-coda",
+  "contextLimit": 180000,
+  "autoCompactThreshold": 0.8,
+  "reasoningEffort": "high"
+}
+```
+
+## Reporting bugs
+
+Email: **support@buehnenproduktionsgesellschaft.de**
+
+For security issues please use the private channel in [SECURITY.md](SECURITY.md).
+
+When reporting, include:
+- Output of `donna --version`
+- `node --version`
+- Operating system
+
+## Platform support
+
+Officially supported: **macOS** and **Linux**. Windows is not supported in
+this release — `run_bash` uses `/bin/bash` and several path helpers assume
+POSIX semantics, so `npm i -g` refuses to install on Windows (`"os"` field
+in `package.json`). Windows support is tracked as issue #4 and planned for
+a future release.
+
+## Development
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+A complete history of changes is in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+Proprietary. Copyright (c) 2026 dbpg deutsche Bühnenproduktionsgesellschaft mbH & Co. KG. All rights reserved.

package/dist/agents/builtin/research/AGENT.md

@@ -0,0 +1,53 @@
+---
+name: research
+description: Deep research agent - reads code and returns structured findings
+allowedTools: [read_file, glob, grep, web_search, web_fetch]
+maxTurns: 19
+timeout: 180000
+---
+
+You are a research agent running in an isolated context. You receive ONE task,
+investigate using `read_file` / `glob` / `grep` / `web_search` / `web_fetch`,
+and ALWAYS return a structured report.
+
+## Mandatory Contract
+- Every run MUST end with a final response containing the report below.
+- Empty content is a critical violation of the agent contract.
+- If the task is impossible (file missing, ambiguous, blocked) you STILL respond — set `Status: failed` and explain why in `Summary`.
+- Your final turn (the one with no tool calls) IS the report. Do not call tools in that turn.
+
+## Workflow
+1. Read the task carefully and extract any paths, symbols, or keywords.
+2. Use `glob`/`grep` to locate relevant files if not given explicitly.
+3. Use `read_file` to inspect them.
+4. Stop investigating after 1–3 evidence-gathering turns and produce the report.
+5. Be concise but specific — quote line numbers, function names, exact paths.
+6. Do NOT write files or execute commands. Read-only.
+
+## Required Output Format
+Your final response MUST start with this exact structure:
+
+```
+## Status
+success | partial | failed
+
+## Summary
+<one sentence directly answering the task>
+
+## Findings
+<structured detail; subsections allowed>
+
+## Key Files
+- `path/to/file.ts:line` — what it does, why it matters
+```
+
+`Key Files` may be empty if no files are central to the answer, but the heading must still be present.
+
+## Output Style (strict)
+- Start the response directly with `## Status`. No preamble ("Sure", "I'll investigate", "Let me check"), no greeting.
+- End after the last finding. No closing pleasantries ("Let me know if...", "Hope this helps").
+- No emojis. No decorative characters.
+- No bold/italic for emphasis — only inside section headers if needed.
+- No prose paragraphs where bullets work. Terse over flowing.
+- Quote exact identifiers: file paths, line numbers, function names, error strings. Never paraphrase them.
+- No filler ("It looks like", "It appears that"). State facts directly.

package/dist/agents/builtin/review/AGENT.md

@@ -0,0 +1,58 @@
+---
+name: review
+description: Code review agent - unbiased analysis of changes
+allowedTools: [read_file, grep]
+maxTurns: 19
+timeout: 180000
+---
+
+You are a code review agent running in an isolated context with no knowledge of
+the surrounding conversation or the author's intent. You judge only what the
+code does.
+
+## Mandatory Contract
+- Every run MUST end with a final response containing the report below.
+- Empty content is a critical violation of the agent contract.
+- If you cannot review (file missing, unreadable, scope unclear) you STILL respond — set `Status: failed` and explain why in `Summary`.
+- Your final turn (no tool calls) IS the report. Do not call tools in that turn.
+
+## Workflow
+1. Read the task to identify what to review (file, range, concern).
+2. Use `read_file` and `grep` to inspect the code.
+3. Look for: bugs, security issues, performance problems, readability concerns.
+4. After 1–3 evidence-gathering turns, produce the report.
+5. Be direct — name files, lines, severities. No hedging.
+
+## Severity Levels
+- `CRITICAL` — bug, security flaw, data loss risk
+- `WARNING` — likely bug, performance issue, smell
+- `INFO` — style, minor improvement
+
+## Required Output Format
+Your final response MUST start with this exact structure:
+
+```
+## Status
+success | partial | failed
+
+## Summary
+<one sentence: count by severity and overall verdict>
+
+## Findings
+### [SEVERITY] <Issue title>
+- **Location**: `file.ts:line`
+- **Problem**: <what's wrong>
+- **Impact**: <why it matters>
+- **Suggestion**: <how to fix, if applicable>
+
+(repeat per finding; if none, write "No issues found.")
+```
+
+## Output Style (strict)
+- Start the response directly with `## Status`. No preamble ("Sure", "I'll review", "Let me look"), no greeting.
+- End after the last finding. No closing pleasantries ("Let me know if...", "Hope this helps").
+- No emojis. No decorative characters.
+- No bold/italic for emphasis — only the labels inside finding entries (Location/Problem/Impact/Suggestion) and section headers.
+- No hedging ("might be", "could potentially"). If you flag an issue, state it as fact with severity.
+- Quote exact identifiers: file paths, line numbers, function names. Never paraphrase them.
+- No filler. One issue, one entry, no surrounding prose.

package/dist/agents/global.d.ts

@@ -0,0 +1,19 @@
+import { AgentManager } from './manager.js';
+import type { AppState } from '../state.js';
+import type { Session } from '../config/store.js';
+export declare let globalAgentManager: AgentManager | null;
+export declare function setGlobalAgentManager(manager: AgentManager): void;
+export declare function getGlobalAgentManager(): AgentManager | null;
+export declare let globalAppState: AppState | null;
+export declare function setGlobalAppState(state: AppState): void;
+export declare function getGlobalAppState(): AppState | null;
+/**
+ * Drain pending async agent results into the session as a synthetic user
+ * turn so the next runConversation call sees them. Returns true if anything
+ * was drained.
+ *
+ * Shared by:
+ *   - processAgentQueue (idle wake-up from listener)
+ *   - runConversation end-of-turn check (drained while a turn was in flight)
+ */
+export declare function drainAgentResults(state: AppState, session: Session): boolean;

package/dist/agents/global.js

@@ -0,0 +1,54 @@
+import { markUserTurnStart } from '../state.js';
+import { saveSession } from '../config/store.js';
+export let globalAgentManager = null;
+export function setGlobalAgentManager(manager) {
+    globalAgentManager = manager;
+}
+export function getGlobalAgentManager() {
+    return globalAgentManager;
+}
+export let globalAppState = null;
+export function setGlobalAppState(state) {
+    globalAppState = state;
+}
+export function getGlobalAppState() {
+    return globalAppState;
+}
+/**
+ * Drain pending async agent results into the session as a synthetic user
+ * turn so the next runConversation call sees them. Returns true if anything
+ * was drained.
+ *
+ * Shared by:
+ *   - processAgentQueue (idle wake-up from listener)
+ *   - runConversation end-of-turn check (drained while a turn was in flight)
+ */
+export function drainAgentResults(state, session) {
+    if (state.agentResultQueue.length === 0)
+        return false;
+    const results = [...state.agentResultQueue];
+    state.agentResultQueue = [];
+    const combinedContent = results
+        .map((r) => {
+        const tokens = `${(r.tokenUsage.prompt / 1000).toFixed(1)}k prompt, ${(r.tokenUsage.completion / 1000).toFixed(1)}k completion`;
+        return `## Result from **${r.agent}** agent (${r.turnsUsed} turns, ${tokens}, ${(r.elapsedMs / 1000).toFixed(1)}s)\n${r.task}\n\n${r.response}`;
+    })
+        .join('\n\n---\n\n');
+    state.items.push({
+        type: 'message',
+        role: 'assistant',
+        content: combinedContent,
+    });
+    // Treat the drained agent results as a real turn boundary: freeze prior
+    // display items and capture a git snapshot before the synthetic user
+    // message, so point-in-time revert works for agent-result-driven turns
+    // (consistent with queued prompts in conversation.ts).
+    markUserTurnStart(state, session);
+    const agentMsg = {
+        role: 'user',
+        content: `[Sub-agent results for ${results.length} task(s):\n\n${results.map((r) => `"${r.task}" (${r.agent})`).join('\n')}]\n\n${combinedContent}`,
+    };
+    session.messages.push(agentMsg);
+    saveSession(session);
+    return true;
+}

package/dist/agents/loader.d.ts

@@ -0,0 +1,9 @@
+import { AgentSpec } from './types.js';
+export interface AgentsLoadResult {
+    agents: AgentSpec[];
+    errors: {
+        file: string;
+        message: string;
+    }[];
+}
+export declare function loadAgents(cwd: string): AgentsLoadResult;

package/dist/agents/loader.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { AGENT_BLOCKED_TOOLS } from './types.js';
+import { parseFrontmatter } from '../skills/frontmatter.js';
+export function loadAgents(cwd) {
+    const agents = [];
+    const errors = [];
+    const dirs = [
+        path.join(cwd, '.donna/agents'),
+        path.join(os.homedir(), '.donna/agents'),
+        path.join(cwd, 'src/agents/builtin'), // Built-in agents from source
+    ];
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const agentFile = path.join(dir, entry.name, 'AGENT.md');
+            if (!fs.existsSync(agentFile))
+                continue;
+            try {
+                const raw = fs.readFileSync(agentFile, 'utf-8');
+                const { frontmatter, body } = parseFrontmatter(raw);
+                // Validate frontmatter
+                const name = String(frontmatter.name || entry.name);
+                const description = String(frontmatter.description || '');
+                const maxTurns = Math.min(Number(frontmatter.maxTurns) || 10, 20); // Hard cap
+                const timeoutMs = Math.min(Number(frontmatter.timeout) || 120000, 300000); // Max 5min
+                // Sanitize allowed tools - block dangerous ones
+                // Parse allowed tools - handle both array syntax [a, b] and missing frontmatter
+                const safeToolsList = ['read_file', 'glob', 'grep', 'web_search', 'web_fetch', 'list_skills'];
+                const allowedToolsRaw = frontmatter.allowedTools;
+                let allowedTools;
+                if (allowedToolsRaw) {
+                    // Parse YAML array format: [tool1, tool2]
+                    const match = String(allowedToolsRaw).match(/^\[([^\]]*)\]$/);
+                    if (match) {
+                        allowedTools = match[1].split(',').map(s => s.trim().replace(/^["']|["']$/g, ''));
+                    }
+                    else {
+                        allowedTools = [allowedToolsRaw];
+                    }
+                    // Filter to only safe tools
+                    allowedTools = allowedTools.filter((t) => !AGENT_BLOCKED_TOOLS.has(t) && safeToolsList.includes(t));
+                    // If nothing valid remains, fall back to safe defaults
+                    if (allowedTools.length === 0) {
+                        allowedTools = [...safeToolsList];
+                    }
+                }
+                else {
+                    // No explicit tools - use all safe defaults
+                    allowedTools = [...safeToolsList];
+                }
+                agents.push({
+                    name: sanitizeAgentName(name),
+                    description,
+                    allowedTools,
+                    maxTurns,
+                    timeoutMs,
+                    filePath: agentFile,
+                    systemPrompt: body.trim(),
+                });
+            }
+            catch (e) {
+                errors.push({ file: agentFile, message: e.message });
+            }
+        }
+    }
+    return { agents, errors };
+}
+function sanitizeAgentName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+}

package/dist/agents/manager.d.ts

@@ -0,0 +1,52 @@
+import { AgentSpec, AgentResult } from './types.js';
+import { AgentPool } from './pool.js';
+import { DonnaConfig } from '../config/schema.js';
+export interface ToolDef {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export declare class AgentManager {
+    private cwd;
+    private agents;
+    private pool;
+    private config;
+    /** One AbortController per in-flight task, so abortAll() can actually
+     *  cancel the running turn loop + its API call — not just the pool
+     *  bookkeeping. */
+    private controllers;
+    /** Non-fatal errors collected during initial agent load. Exposed so the
+     *  TUI can surface them via /agents or a status indicator instead of
+     *  writing to stdout/stderr and corrupting the Ink render. */
+    readonly loadErrors: string[];
+    constructor(cwd: string, config: DonnaConfig);
+    private load;
+    getPool(): AgentPool;
+    getAgent(name: string): AgentSpec | undefined;
+    listAgents(): AgentSpec[];
+    /**
+     * Submit task and optionally wait for completion.
+     * @param options.wait - If true, blocks until completion. If false, returns immediately with task ID.
+     * @returns Task ID (async) or AgentResult (sync when wait=true)
+     */
+    submitTask(name: string, task: string, files?: string[], options?: {
+        wait?: boolean;
+        waitTimeoutMs?: number;
+    }): Promise<string | AgentResult>;
+    private executeWhenReady;
+    /** Resolve once the task reaches a terminal-or-running state, driven by
+     *  pool notifications instead of polling. Also resolves on abort. */
+    private waitForRunning;
+    /** Get tool definition for API */
+    getToolDef(): ToolDef | null;
+    /** Wait for task completion and return result (blocking).
+     *  Event-driven off pool notifications — no polling. */
+    waitForResult(taskId: string, timeoutMs?: number): Promise<AgentResult>;
+    /** Abort every in-flight and queued agent — cancels the running turn loop
+     *  and its API call via the per-task AbortController, then clears pool
+     *  bookkeeping. Call on app exit / Ctrl+C. */
+    abortAll(): void;
+}