replicas-engine 0.1.99 → 0.1.101

package/dist/src/index.js

@@ -1091,7 +1091,7 @@ function parseReplicasConfigString(content, filename) {
 }
 
 // ../shared/src/engine/environment.ts
-var DAYTONA_SNAPSHOT_ID = "13-04-2026-royal-york-v2";
+var DAYTONA_SNAPSHOT_ID = "13-04-2026-royal-york";
 
 // ../shared/src/engine/types.ts
 var DEFAULT_CHAT_TITLES = {
@@ -1643,6 +1643,7 @@ var PreviewService = class {
 var previewService = new PreviewService();
 
 // src/services/chat/chat-service.ts
+import { existsSync as existsSync7 } from "fs";
 import { mkdir as mkdir10, readFile as readFile8, rm, writeFile as writeFile8 } from "fs/promises";
 import { homedir as homedir9 } from "os";
 import { join as join11 } from "path";
@@ -3076,23 +3077,27 @@ async function getChatFinalResponse(chatId) {
   }
   return "[No response from subagent]";
 }
-function buildSpawnAgentTool(parentChatId) {
+function buildSpawnAgentTool(parentChatId, codexAvailable = false) {
+  const providerEnum = codexAvailable ? z.enum(["claude", "codex", "relay"]) : z.enum(["claude", "relay"]);
+  const providerDesc = codexAvailable ? "Which agent to use. Prefer codex for code writing, claude for exploration/analysis, relay for complex multi-step orchestration." : "Which agent to use. Use claude for code writing, exploration, and analysis. Use relay for complex multi-step orchestration.";
+  const useCases = codexAvailable ? `- Complex code writing tasks (use provider 'codex' with a capable model)
+- Codebase exploration that would consume many tokens (use provider 'claude')` : `- Complex code writing tasks (use provider 'claude')
+- Codebase exploration that would consume many tokens (use provider 'claude')`;
   return tool(
     "spawn_agent",
     `Spawn a new subagent to perform a task. The subagent runs in its own chat with a fresh context window.
 
 Use this for:
-- Complex code writing tasks (use provider 'codex' with a capable model)
-- Codebase exploration that would consume many tokens (use provider 'claude')
+${useCases}
 - Browser testing, large test runs, or other token-heavy operations
 - Any task you want to delegate to preserve your own context
 
 The tool blocks until the subagent completes and returns its final response.
 You will also receive the chatId so you can send follow-up messages or clean up the chat.`,
     {
-      provider: z.enum(["claude", "codex", "relay"]).describe("Which agent to use. Prefer codex for code writing, claude for exploration/analysis, relay for complex multi-step orchestration."),
+      provider: providerEnum.describe(providerDesc),
       prompt: z.string().describe("The full prompt/instructions for the subagent. Be detailed - it has no context from your conversation."),
-      model: z.string().optional().describe("Model override. Claude: opus, sonnet, haiku. Codex: gpt-5.4, gpt-5.3-codex, etc."),
+      model: z.string().optional().describe(codexAvailable ? "Model override. Claude: opus, sonnet, haiku. Codex: gpt-5.4, gpt-5.3-codex, etc." : "Model override. Claude: opus, sonnet, haiku."),
       title: z.string().optional().describe("Optional title for the subagent chat (for identification)."),
       timeout_minutes: z.number().positive().optional().describe("Timeout in minutes for the subagent to complete (default: 10). Set higher for large tasks to avoid losing work.")
     },
@@ -3208,11 +3213,11 @@ var deleteAgentTool = tool(
     }
   }
 );
-function createRelayMcpServer(parentChatId) {
+function createRelayMcpServer(parentChatId, codexAvailable = false) {
   return createSdkMcpServer({
     name: "relay-subagent-tools",
     version: "1.0.0",
-    tools: [buildSpawnAgentTool(parentChatId), messageAgentTool, deleteAgentTool]
+    tools: [buildSpawnAgentTool(parentChatId, codexAvailable), messageAgentTool, deleteAgentTool]
   });
 }
 
@@ -3314,12 +3319,17 @@ function getUsingToolsSection() {
   ];
   return [`# Using your tools`, ...prependBullets(items)].join("\n");
 }
-function getDelegationSection() {
+function getDelegationSection(codexAvailable) {
+  const providerList = codexAvailable ? "claude, codex, or relay" : "claude or relay";
+  const spawnDesc = `Create a new subagent with a specific provider (${providerList}), send it a prompt, and wait for its response. Returns the chatId and the agent's final response. You can set a custom timeout via the timeout_minutes parameter (default: 10 minutes).`;
+  const agentSelectionLines = codexAvailable ? `Use provider 'codex' for heavy code writing, implementation, and large refactors. Suggested models: gpt-5.4 (default), gpt-5.3-codex.
+
+Use provider 'claude' for codebase exploration, code review, planning, complex debugging, and tasks requiring nuanced architectural understanding. Suggested models: opus (default), sonnet (faster).` : `Use provider 'claude' for all tasks including code writing, codebase exploration, code review, planning, complex debugging, and tasks requiring nuanced architectural understanding. Suggested models: opus (default), sonnet (faster).`;
   return `# Delegation
 
 You have three subagent tools for spawning and managing agents that run in separate context windows:
 
-- **spawn_agent**: Create a new subagent with a specific provider (claude or codex), send it a prompt, and wait for its response. Returns the chatId and the agent's final response. You can set a custom timeout via the timeout_minutes parameter (default: 10 minutes).
+- **spawn_agent**: ${spawnDesc}
 - **message_agent**: Send a follow-up message to an existing subagent by chatId. Use for iteration, corrections, or additional requests in the same context.
 - **delete_agent**: Delete a subagent chat when you no longer need it.
 
@@ -3339,7 +3349,15 @@ Your primary resource is your context window. Every tool call result, every code
 
 ## Parallel execution
 
-You can spawn multiple subagents in parallel by making multiple spawn_agent tool calls in a single response. Do this whenever you have independent tasks \u2014 do NOT call them sequentially if they don't depend on each other. For example, if you need to test three endpoints, spawn three subagents in one response, not one after another.
+You can spawn multiple subagents in parallel by making multiple spawn_agent tool calls in a single response. Do this whenever you have truly independent tasks \u2014 do NOT call them sequentially if they don't depend on each other. For example, if you need to test three endpoints, spawn three subagents in one response, not one after another.
+
+**IMPORTANT \u2014 recognize implicit dependencies:** Tasks are NOT independent when one task's output shapes what the other needs to know. The most common case: if you are building both a backend and a frontend, the frontend depends on the backend \u2014 it needs to know the API endpoints, request/response shapes, data models, etc. You MUST complete the backend subagent first, then use its output to write an informed prompt for the frontend subagent. Other examples of implicit dependencies:
+- Building a library/SDK and code that consumes it
+- Creating a database schema and code that queries it
+- Implementing an API and writing tests for that API
+- Any producer/consumer relationship where the consumer needs to match the producer's interface
+
+When in doubt about whether tasks are independent, run them sequentially. The cost of unnecessary sequencing is just latency; the cost of incorrect parallelization is a subagent working blind and producing incompatible code.
 
 ## Testing your work
 
@@ -3357,9 +3375,20 @@ The default subagent timeout is 10 minutes. For tasks you expect to take longer
 
 ## Agent selection
 
-Use provider 'codex' for heavy code writing, implementation, and large refactors. Suggested models: gpt-5.4 (default), gpt-5.3-codex.
+${agentSelectionLines}
+
+## Incremental progress on complex tasks
 
-Use provider 'claude' for codebase exploration, code review, planning, complex debugging, and tasks requiring nuanced architectural understanding. Suggested models: opus (default), sonnet (faster).
+For complex, multi-step tasks (building a full feature, large refactors, new systems), do NOT try to accomplish everything in one shot. Instead, take an incremental commits approach \u2014 work step by step, feature by feature, commit by commit.
+
+**How to work incrementally:**
+- Break the task into discrete, meaningful steps (e.g., schema first, then API endpoints, then frontend, then tests).
+- After each step, commit the work in a clean state before moving on. By clean state, we mean the kind of code that is stable, does not introduce major bugs, the code is orderly and well-documented. A good rule of thumb is: could another agent or human pick up from this commit and continue building without having to clean up an unrelated mess?
+- Review the results of each step before starting the next. This lets you catch issues early, adjust course, and carry accurate context forward about what was already built.
+
+**Why this matters:** Trying to build an entire system in one shot tends to produce lower-quality, harder-to-debug output. Incremental commits create natural checkpoints \u2014 if something goes wrong, you only lose one step's worth of work, not everything. This approach also preserves your context window since you track high-level progress without holding all the implementation details.
+
+**When to use this:** Apply incremental progress for tasks that span multiple components, require many files to be changed, or would otherwise be a large, complex, time-consuming piece of work. For simple, self-contained tasks (a bug fix, a single endpoint, a small refactor), working in one pass is fine.
 
 ## Effective delegation
 
@@ -3412,14 +3441,15 @@ function getEnvironmentSection() {
     ...prependBullets(envItems.filter((x) => x !== null))
   ].join("\n");
 }
-function buildRelaySystemPrompt(customInstructions) {
+function buildRelaySystemPrompt(options) {
+  const { customInstructions, codexAvailable } = options ?? {};
   const sections = [
     getIntroSection(),
     getSystemSection(),
     getDoingTasksSection(),
     getActionsSection(),
     getUsingToolsSection(),
-    getDelegationSection(),
+    getDelegationSection(codexAvailable ?? false),
     getToneAndStyleSection(),
     getOutputEfficiencySection(),
     getEnvironmentSection(),
@@ -3446,12 +3476,13 @@ var RELAY_TOOLS = [
 var RelayManager = class {
   inner;
   constructor(options) {
+    const codexAvailable = options.codexAvailable ?? false;
     this.inner = new ClaudeManager({
       ...options,
-      systemPromptOverride: buildRelaySystemPrompt,
+      systemPromptOverride: (customInstructions) => buildRelaySystemPrompt({ customInstructions, codexAvailable }),
       tools: RELAY_TOOLS,
       mcpServers: {
-        "relay-subagent-tools": createRelayMcpServer(options.chatId)
+        "relay-subagent-tools": createRelayMcpServer(options.chatId, codexAvailable)
       },
       envOverrides: {
         CLAUDE_CODE_STREAM_CLOSE_TIMEOUT: "900000"
@@ -3550,6 +3581,10 @@ var ENGINE_DIR2 = join11(homedir9(), ".replicas", "engine");
 var CHATS_FILE = join11(ENGINE_DIR2, "chats.json");
 var CLAUDE_HISTORY_DIR = join11(ENGINE_DIR2, "claude-histories");
 var RELAY_HISTORY_DIR = join11(ENGINE_DIR2, "relay-histories");
+var CODEX_AUTH_PATH2 = join11(homedir9(), ".codex", "auth.json");
+function isCodexAvailable() {
+  return existsSync7(CODEX_AUTH_PATH2) || Boolean(ENGINE_ENV.OPENAI_API_KEY);
+}
 function isPersistedChat(value) {
   if (!isRecord(value)) {
     return false;
@@ -3761,7 +3796,8 @@ var ChatService = class {
         onSaveSessionId: saveSession,
         onTurnComplete: onProviderTurnComplete,
         onEvent: onProviderEvent,
-        chatId: persisted.id
+        chatId: persisted.id,
+        codexAvailable: isCodexAvailable()
       });
     } else {
       provider = new CodexManager({
@@ -3972,7 +4008,7 @@ var planService = new PlanService();
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify3 } from "util";
 import { readFile as readFile11 } from "fs/promises";
-import { existsSync as existsSync7 } from "fs";
+import { existsSync as existsSync8 } from "fs";
 import { join as join14 } from "path";
 
 // src/services/warm-hook-logs-service.ts
@@ -4074,7 +4110,7 @@ async function executeHookScript(params) {
 async function readRepoWarmHook(repoPath) {
   for (const filename of REPLICAS_CONFIG_FILENAMES) {
     const configPath = join14(repoPath, filename);
-    if (!existsSync7(configPath)) {
+    if (!existsSync8(configPath)) {
       continue;
     }
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-engine",
-  "version": "0.1.99",
+  "version": "0.1.101",
   "description": "Lightweight API server for Replicas workspaces",
   "type": "module",
   "main": "dist/src/index.js",