omnara 0.1.6 → 0.1.9

package/dist/config/omnara-config.d.ts

@@ -0,0 +1,34 @@
+import * as z from 'zod';
+export type OmnaraConfig = z.infer<typeof OmnaraConfig>;
+declare const OmnaraConfig: z.ZodObject<{
+    worktrees: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+    }, {
+        enabled?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    worktrees: {
+        enabled: boolean;
+    };
+}, {
+    worktrees?: {
+        enabled?: boolean | undefined;
+    } | undefined;
+}>;
+/**
+ * Read and parse the omnara.jsonc configuration file
+ *
+ * @param configPath - Path to the config file (defaults to omnara.jsonc in cwd)
+ * @returns Parsed configuration or default config if file doesn't exist
+ */
+export declare function readOmnaraConfig(configPath?: string): Promise<OmnaraConfig>;
+/**
+ * Check if worktrees are enabled in the configuration
+ *
+ * @param config - The omnara configuration
+ * @returns true if worktrees should be enabled
+ */
+export declare function isWorktreesEnabled(config: OmnaraConfig): boolean;
+export {};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestrator/agent-orchestrator.d.ts

@@ -2,10 +2,12 @@ import { type AgentClient } from './ai-client.js';
 import { Session } from './session.js';
 import { WorkerManager } from './worker-manager.js';
 import type { InboundMessage, OutboundMessage } from './orchestrator-types.js';
+import type { McpServerConfig } from '@anthropic-ai/claude-agent-sdk';
 interface AgentOrchestratorDependencies {
     createMainClient?: () => AgentClient;
-    createWorkerClient?: () => AgentClient;
+    createWorkerClient?: (mcpServers?: Record<string, McpServerConfig>, cwd?: string) => AgentClient;
     workerManager?: WorkerManager;
+    repoPath?: string;
 }
 export interface AgentOrchestratorClientAdapter {
     send: (message: OutboundMessage) => void;

package/dist/orchestrator/orchestrator-prompt.d.ts

@@ -4,5 +4,5 @@
  * The orchestrator's role is to coordinate and delegate work, not to execute tasks directly.
  * It should ALWAYS use workers to handle all implementation work.
  */
-import ORCHESTRATOR_SYSTEM_PROMPT from './orchestrator-prompt.md';
+declare const ORCHESTRATOR_SYSTEM_PROMPT: string;
 export { ORCHESTRATOR_SYSTEM_PROMPT };

package/dist/orchestrator/orchestrator-prompt.md

@@ -4,6 +4,31 @@ You are Omnara, an orchestrator agent responsible for coordinating work through
 
 ## Core Principles
 
+## CRITICAL: Tool Usage Restrictions
+
+**YOU ARE FORBIDDEN FROM USING THESE TOOLS DIRECTLY:**
+- **Write** - NEVER create or overwrite files directly
+- **Edit** - NEVER modify file contents directly
+- **Bash** - NEVER execute commands directly (git, npm, tests, etc.)
+- **NotebookEdit** - NEVER modify Jupyter notebooks directly
+
+**ANY action that modifies system state MUST be delegated to a worker.**
+
+**YOU MAY ONLY USE THESE READ-ONLY TOOLS:**
+- **Read** - For quick context gathering (1-2 files max)
+- **Grep** - For quick searches (single search only)
+- **Glob** - For finding file patterns
+- **WebFetch / WebSearch** - For external information
+- **TodoWrite** - For tracking task progress
+
+**If you attempt to use Write, Edit, Bash, or NotebookEdit tools, you are VIOLATING your core directive.**
+
+**Why this restriction exists:**
+- Using these tools blocks your context and makes you unresponsive
+- Workers can execute these operations in parallel without blocking you
+- Your job is to coordinate, not to implement
+- State-modifying operations must go through proper delegation channels
+
 **STAY RESPONSIVE - Your Most Important Job**:
 
 The orchestrator must remain responsive to handle user interactions in a conversational environment. When you execute tool calls or perform work directly, you BLOCK your own context and cannot respond to new user messages.
@@ -33,13 +58,14 @@ The orchestrator must remain responsive to handle user interactions in a convers
 3. Launch worker(s) with complete context and clear instructions
 4. Return control immediately - stay responsive for user interaction
 
-**When to use tools yourself (RARE)**:
+**When to use tools yourself (RARE - READ-ONLY TOOLS ONLY)**:
 - Single quick lookup (1-2 tool calls max, < 5 seconds)
 - Answering "what/where/how does X work?" questions IF it's a single file or simple pattern
 - If you're uncertain or it might take longer: delegate instead
+- **REMINDER: You may ONLY use Read, Grep, Glob, WebFetch, WebSearch, TodoWrite - NEVER Write, Edit, Bash, or NotebookEdit**
 
 **When to delegate to workers (ALMOST ALWAYS)**:
-- ANY code modification, file writing, or command execution
+- **ANY code modification, file writing, or command execution** (Write, Edit, Bash, NotebookEdit are FORBIDDEN for you)
 - Reading 2+ files or doing any analysis
 - Multi-step research or investigation tasks
 - Running tests, git operations, deployments
@@ -56,13 +82,16 @@ The orchestrator must remain responsive to handle user interactions in a convers
 
 ## Using Your Tools Effectively
 
-You have read-only tools available: **Read, Grep, Glob, WebFetch, WebSearch, TodoWrite**
+**You ONLY have access to these READ-ONLY tools:** Read, Grep, Glob, WebFetch, WebSearch, TodoWrite
+
+**YOU ARE EXPLICITLY FORBIDDEN from using:** Write, Edit, Bash, NotebookEdit
 
 **Key tips**:
 - **Stay responsive**: Avoid blocking your context with work - delegate instead of using tools directly
 - **Limit tool use**: If you must use tools, limit to 1-2 calls maximum, then delegate
 - **Code references**: Use `file_path:line_number` format when explaining locations
 - **Prefer delegation**: When in doubt, delegate to a worker to keep your context responsive
+- **Never modify state**: All file modifications and command executions MUST go through workers
 
 ## Managing Todos with TodoWrite
 
@@ -309,6 +338,84 @@ Response:
 
 **Edge Case - Minor Dependencies**: Even if there's a soft dependency (e.g., docs should reflect the code), prefer parallel execution. Workers can read the latest code state, so documentation can be written based on the new code even if both workers run simultaneously.
 
+## Git Worktree Isolation
+
+Workers can optionally operate in ISOLATED git worktrees, providing complete isolation from the main repository and from other workers. You control this via the `worktree_name` parameter when launching a worker.
+
+**Controlling Worktree Isolation:**
+- Set `worktree_name` when calling `launch_worker` to specify the worktree context
+- Each worktree provides a completely isolated file system view and git state
+- Multiple workers can share the same worktree context or have separate ones
+- If not specified, the worker operates in the main repository
+
+**What Isolated Workers Get:**
+- **Dedicated working directory** - Separate file system view in `.omnara/worktrees/`
+- **Dedicated git branch** - Isolated branch for that worktree context
+- **Independent git state** - Separate staging area, no shared commits, independent checkouts
+
+**Key Benefits:**
+1. **No Conflicts**: Workers in different worktrees can edit the same files simultaneously without interfering
+2. **Safe Operations**: Workers can stage, commit, and manipulate git state independently
+3. **Clean Isolation**: Main repository remains untouched until worker results are reviewed and merged
+4. **Controlled Sharing**: Workers with the same worktree_name share the same isolated environment
+
+**Best Practices:**
+- Use worktree isolation when workers need to modify the same files independently
+- Workers in the same worktree_name share the same isolated environment
+- Workers in different worktree contexts are completely isolated from each other
+- Review worker branches before merging changes to main
+- Trust the isolation - workers in different worktrees truly cannot interfere with each other
+
+**Worker Launch Information:**
+When you launch a worker with worktree isolation, you'll receive:
+- `worktree_path`: Location of the worker's isolated directory
+- `branch_name`: Name of the worktree's dedicated branch
+
+**Examples:**
+
+**Example 1: Parallel Edits to Same File**
+```
+User: "Add error handling to login.ts and also add logging to the same file"
+
+Response:
+- Launch worker 1 with worktree_name="feature-1": "Add error handling to login.ts"
+- Launch worker 2 with worktree_name="feature-2": "Add logging to login.ts"
+  ✓ Safe - each worker has isolated copy in different worktrees, changes can be merged later
+```
+
+**Example 2: Shared Worktree Context**
+```
+User: "Refactor the authentication system across multiple files"
+
+Response:
+- Launch worker 1 with worktree_name="auth-refactor": "Refactor authentication middleware"
+- Launch worker 2 with worktree_name="auth-refactor": "Update authentication tests"
+  ✓ Both workers share the same isolated worktree, can see each other's changes
+```
+
+**Example 3: Mixed Isolation**
+```
+User: "Fix bug in production code and experiment with a new feature"
+
+Response:
+- Launch worker 1 (no worktree_name): "Fix critical bug in production code"
+  ✓ Works in main repository
+- Launch worker 2 with worktree_name="new-feature": "Experiment with WebSocket implementation"
+  ✓ Isolated in its own worktree, won't affect main code
+```
+
+**Example 4: Complex Sequential Work**
+```
+User: "Research authentication libraries, then implement the best one"
+
+Response:
+- Launch worker 1 (no worktree_name): "Research Node.js authentication libraries and recommend the best option"
+  [Wait for completion...]
+- Review worker 1's recommendation
+- Launch worker 2 with worktree_name="auth-impl": "Implement {recommended library} based on research"
+  ✓ Implementation isolated in worktree for safe experimentation
+```
+
 ## Worker Status Tracking
 
 **Status in Message History**: When workers complete, a special status update message is added to the conversation history. This message shows:
@@ -383,6 +490,12 @@ You will be automatically triggered when workers complete. Each time this happen
 - Delegate liberally - it's not just good practice, it's architecturally required
 - Users need a responsive conversational partner, not a busy worker
 
+**Tool Usage Restrictions (CRITICAL)**:
+- **NEVER use Write, Edit, Bash, or NotebookEdit** - These are FORBIDDEN for orchestrators
+- **ONLY use Read, Grep, Glob, WebFetch, WebSearch, TodoWrite** - Read-only tools only
+- **ANY state modification MUST be delegated to workers** - No exceptions
+- If you find yourself about to use a forbidden tool, STOP and delegate instead
+
 **Your role:**
 - You are a COORDINATOR, not an IMPLEMENTER
 - Workers are your hands - you are the brain

package/dist/orchestrator/orchestrator-types.d.ts

@@ -116,6 +116,8 @@ export type OutboundMessage = {
     durationMs?: number;
     costUsd?: number;
     message?: string;
+    worktree_path?: string;
+    branch_name?: string;
     metadata?: Record<string, unknown>;
     messageId?: string;
 } | {

package/dist/orchestrator/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { WorktreeManager, WorktreeError, type WorktreeManagerOptions, type WorktreeInfo, } from './worktree-manager.js';
+export { AsyncQueue } from './async-queue.js';
+export type { SessionLogger } from './session-logger.js';

package/dist/orchestrator/utils/worktree-manager.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Configuration options for WorktreeManager
+ */
+export interface WorktreeManagerOptions {
+    /**
+     * The root directory of the git repository
+     */
+    repoPath: string;
+    /**
+     * Base directory for worktrees (default: .omnara/worktrees)
+     */
+    worktreeBasePath?: string;
+    /**
+     * Whether worktrees are enabled (default: false)
+     */
+    enabled?: boolean;
+}
+/**
+ * Information about a created worktree
+ */
+export interface WorktreeInfo {
+    /**
+     * Unique identifier for the worker
+     */
+    workerId: string;
+    /**
+     * Semantic name for the worktree (e.g., "main-feature", "bugfix-auth")
+     */
+    worktreeName: string;
+    /**
+     * Absolute path to the worktree directory
+     */
+    worktreePath: string;
+    /**
+     * Name of the branch created for this worktree
+     */
+    branchName: string;
+    /**
+     * Timestamp when the worktree was created
+     */
+    createdAt: Date;
+}
+/**
+ * Error thrown when worktree operations fail
+ */
+export declare class WorktreeError extends Error {
+    readonly workerId: string;
+    readonly operation: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, workerId: string, operation: string, cause?: Error | undefined);
+}
+/**
+ * Manages git worktrees for worker isolation
+ *
+ * This class handles the lifecycle of git worktrees, ensuring each worker
+ * operates in an isolated environment. It provides methods for creating,
+ * managing, and cleaning up worktrees.
+ *
+ * @example
+ * ```typescript
+ * const manager = new WorktreeManager({ repoPath: '/path/to/repo' });
+ * const info = await manager.createWorktree('worker-123', 'main-feature');
+ * // Worker operates in info.worktreePath
+ * await manager.removeWorktree('worker-123');
+ * ```
+ */
+export declare class WorktreeManager {
+    private readonly git;
+    private readonly repoPath;
+    private readonly worktreeBasePath;
+    private readonly activeWorktrees;
+    private readonly enabled;
+    constructor(options: WorktreeManagerOptions);
+    /**
+     * Validate that the repoPath is a git repository
+     * Logs an error if worktrees are enabled but not in a git repository
+     */
+    private validateGitRepository;
+    /**
+     * Check if worktrees are enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Creates a new worktree for the specified worker
+     *
+     * @param workerId - Unique identifier for the worker
+     * @param worktreeName - Semantic name for the worktree (e.g., "main-feature", "bugfix-auth")
+     * @returns Information about the created worktree
+     * @throws {WorktreeError} If worktree creation fails
+     */
+    createWorktree(workerId: string, worktreeName: string): Promise<WorktreeInfo>;
+    /**
+     * Removes a worktree for the specified worker
+     *
+     * @param workerId - Unique identifier for the worker
+     * @param force - Force removal even if there are uncommitted changes
+     * @throws {WorktreeError} If worktree removal fails
+     */
+    removeWorktree(workerId: string, force?: boolean): Promise<void>;
+    /**
+     * Gets information about a worker's worktree
+     *
+     * @param workerId - Unique identifier for the worker
+     * @returns Worktree information or undefined if not found
+     */
+    getWorktreeInfo(workerId: string): WorktreeInfo | undefined;
+    /**
+     * Lists all active worktrees managed by this instance
+     *
+     * @returns Array of worktree information
+     */
+    listActiveWorktrees(): WorktreeInfo[];
+    /**
+     * Cleans up all active worktrees
+     *
+     * This method should be called during application shutdown to ensure
+     * all worktrees are properly cleaned up.
+     *
+     * @param force - Force removal even if there are uncommitted changes
+     */
+    cleanupAll(force?: boolean): Promise<void>;
+    /**
+     * Parses the output of 'git worktree list --porcelain'
+     *
+     * @param output - Raw output from git worktree list
+     * @returns Array of worktree paths
+     */
+    private parseWorktreeList;
+    /**
+     * Checks if the repository is in a clean state for worktree operations
+     *
+     * @returns True if repository is clean
+     */
+    isRepositoryClean(): Promise<boolean>;
+}

package/dist/orchestrator/worker-manager.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'events';
-import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { SDKUserMessage, McpServerConfig } from '@anthropic-ai/claude-agent-sdk';
 import type { AgentClient } from './ai-client.js';
 import { AsyncQueue } from './utils/async-queue.js';
 export type WorkerStatus = 'running' | 'completed' | 'error' | 'canceled';
@@ -21,6 +21,10 @@ export interface WorkerRecord {
     error?: string;
     metadata?: Record<string, unknown>;
     messageQueue: AsyncQueue<SDKUserMessage>;
+    worktreePath?: string;
+    branchName?: string;
+    work_context?: string;
+    worktree_name?: string;
 }
 export interface WorkerMessageEvent {
     record: WorkerRecord;
@@ -36,18 +40,27 @@ export interface WorkerMessageEvent {
 interface LaunchWorkerOptions {
     task: string;
     prompt: string;
+    work_context: string;
+    worktree_name: string;
     originSessionId?: string;
     metadata?: Record<string, unknown>;
 }
 interface WorkerManagerOptions {
-    createClient: (mcpServers?: Record<string, any>) => AgentClient;
+    createClient: (mcpServers?: Record<string, McpServerConfig>, cwd?: string) => AgentClient;
     resolveSessionIdBySdk?: (sdkSessionId?: string) => string | undefined;
+    repoPath: string;
 }
 export declare class WorkerManager extends EventEmitter {
     private readonly options;
     private readonly workers;
     private readonly runningQueries;
+    private worktreeManager;
+    private configInitialized;
     constructor(options: WorkerManagerOptions);
+    /**
+     * Initialize the configuration and update WorktreeManager accordingly
+     */
+    private initializeConfig;
     listWorkers(): WorkerRecord[];
     getWorker(id: string): WorkerRecord | undefined;
     getWorkerByTask(task: string): WorkerRecord | undefined;
@@ -56,23 +69,26 @@ export declare class WorkerManager extends EventEmitter {
      * Returns a string describing all active workers and their current state.
      */
     getWorkerStatusSummary(): string;
-    launchWorker({ task, prompt, originSessionId, metadata }: LaunchWorkerOptions): WorkerRecord;
+    launchWorker({ task, prompt, work_context, worktree_name, originSessionId, metadata }: LaunchWorkerOptions, toolUseId?: string): WorkerRecord;
+    private createWorktreeAndRun;
     cancelWorker(id: string): boolean;
     /**
-     * Send a message to a running worker.
+     * Send a message to a worker (running or completed).
      *
      * @param task - The task name of the worker to message
      * @param message - The message content to send
      * @param interrupt - If true, interrupt current generation; if false, queue for next turn
-     * @returns true if message was sent, false if worker not found or not running
+     * @param toolUseId - Optional tool use ID to track this operation for relay forwarding
+     * @returns true if message was sent, false if worker not found or message queue is closed
      */
-    messageWorker(task: string, message: string, interrupt: boolean): Promise<boolean>;
+    messageWorker(task: string, message: string, interrupt: boolean, toolUseId?: string): Promise<boolean>;
     private emitUpdate;
     private emitCompleted;
     private handleStatusUpdate;
     /**
      * Create an async iterable stream of user messages for the worker.
      * Yields the initial prompt, then streams any additional messages from the queue.
+     * If initialPrompt is empty, skips the initial yield and only consumes from the queue.
      */
     private createMessageStream;
     private runWorker;
@@ -81,5 +97,10 @@ export declare class WorkerManager extends EventEmitter {
     private extractDeltaText;
     private extractError;
     private wrapPrompt;
+    /**
+     * Shutdown the worker manager and cleanup all resources
+     * This should be called during application shutdown to ensure all worktrees are cleaned up
+     */
+    shutdown(): Promise<void>;
 }
 export {};