agents-relay 1.0.30 → 1.0.32

package/README.md

@@ -31,9 +31,16 @@ npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id chil
   --capabilities model,chatgpt,browser-harness
 ~~~
 
-Jobs default to `fixed`, preserving the original submit-and-run behavior. Use
-`--mode autonomous` with `init` or `job create` to make reconciliation own
-planner progress. The durable status JSON and dashboard show the mode. An
+Jobs default to `fixed`, preserving the original submit-and-run behavior. Every
+executable task is now created by a completed durable planning decision. `job
+create --start` records `planner-0` (supplied by the orchestrator) and the
+initial task atomically from the caller's perspective; retrying the command is
+idempotent. Use `--mode autonomous` with `init` or `job create` to make
+reconciliation own planner progress. Autonomous creation with only an objective
+may create a model planner first, but it cannot materialize work until that
+planner succeeds. Fixed jobs never grow another planning round.
+
+The durable status JSON and dashboard show the mode and planning provenance. An
 autonomous runtime uses the bundled `skills/agents-relay/agents/planner.agent.md` by default; `--planner-command` is an optional override
 snapshot as JSON on stdin and must return `{ "objective_status": "in_progress"|"satisfied", "assessment": "...", "next_tasks": [...] }`.
 Planner-created tasks use stable IDs and the existing parent/subtask tree, so
@@ -93,6 +100,14 @@ V1 assumes one active runner/daemon per job. Use a distributed atomic lease befo
 
 Codex/model-backed tasks require --provider and --model (or equivalent routing metadata) before launch. See [docs/architecture.md](docs/architecture.md) and [skills/agents-relay/SKILL.md](skills/agents-relay/SKILL.md).
 
+XChat and other orchestrators can consume Relay's exact shared discovery implementation without duplicating filesystem search logic:
+
+~~~sh
+npx agents-relay context resolve --project-path ~/Workspace/agents-relay --role orchestrator
+~~~
+
+The command resolves concrete paths only for the current execution. Use `--skills` / `--agents` for explicit selections; no resolved absolute path is written into durable task state.
+
 The minimal agent-network surface is machine-driven registration and discovery. `agent-register` persists an agent identity, responsibility boundary, claimed capabilities, endpoint/runtime, availability, and routing metadata in a trusted PR marker; `agent-discover` applies hard filters and returns evidence-backed candidates. Adapters remain runtimes, not agent identities. See [docs/architecture.md](docs/architecture.md) for the constrained future remote submission contract.
 
 ### Agent worker lifecycle
@@ -103,7 +118,7 @@ Every model-backed task declares a durable output with `--output task-pr` or `--
 
 For Codex and ChatGPT, **events are authoritative task state**. Event publication uses the canonical Neo `events-bus` surface (`events__publish` for sandboxed/hosted workers, or `NEO_EVENTS_EMIT` for direct local workers); Agents Relay only subscribes and reconciles. Relay publishes `task.process.launched` only after successful adapter launch; `task.started` is worker-owned and must be a new, correlated start acknowledgement. Codex publishes `task.process.exited` when its synchronous runtime exits, while ChatGPT publishes `task.process.async_exited` after its submission runtime exits; neither substitutes for `task.completed`, `task.failed`, `task.blocked`, or `task.cancelled`. The ChatGPT worker-owned tab follows the configured close policy: `after-start` waits for the correlated start acknowledgement, `never` keeps it open for debug, and `after-terminal` waits for a new exact-task terminal event; start-ack failure closes only the owned tab after 60 seconds. The executing agent must publish exactly one correlated terminal event. Relay persists the matching durable state only from that terminal event. Model-backed tasks require an event bus and time out explicitly if no terminal event arrives.
 
-The ChatGPT adapter uses the packaged `chatgpt-browser-worker` as a one-shot submitter. It opens a fresh Temporary Chat tab, uses the account defaults, submits the prompt, verifies acceptance, and applies `--chatgpt-tab-close-policy` (or `AGENTS_RELAY_CHATGPT_TAB_CLOSE_POLICY`): `after-start` by default, `never` for test/debug, or `after-terminal` after a new exact-task terminal event. It never closes a user tab and does not poll for the assistant response, resume/reopen a thread, or use conversation text as the result channel. Any observed ChatGPT thread ID is diagnostic only.
+The ChatGPT adapter uses the `chatgpt-browser-worker` path selected by the shared execution-context resolver; Relay does not bundle its own copy. The resolver applies project-local > Neo shared > global `~/.agents` precedence at execution time, so durable tasks store names/intent rather than stale absolute skill paths. It opens a fresh Temporary Chat tab, uses the account defaults, submits the prompt, verifies acceptance, and applies `--chatgpt-tab-close-policy` (or `AGENTS_RELAY_CHATGPT_TAB_CLOSE_POLICY`): `after-start` by default, `never` for test/debug, or `after-terminal` after a new exact-task terminal event. It never closes a user tab and does not poll for the assistant response, resume/reopen a thread, or use conversation text as the result channel. Any observed ChatGPT thread ID is diagnostic only.
 
 ~~~sh
 npx agents-relay submit --repo OWNER/REPO --pr 5 --id job-1 \

package/dist/adapters.js

@@ -1,8 +1,6 @@
 import { spawn } from 'node:child_process';
 import { access, readFile, writeFile, unlink } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 export function buildCodexArgs(route, input) {
     const args = ['exec', '--json'];
@@ -108,33 +106,23 @@ export class LaunchFailure extends Error {
 }
 export class StartAckTimeout extends LaunchFailure {
 }
-function browserWorkerCandidates(explicit) {
-    const roots = (process.env.AGENTS_RELAY_SKILL_ROOTS ?? '').split(':').filter(Boolean);
-    const packageSkills = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
-    return [
-        explicit,
-        ...roots,
-        packageSkills,
-        join(homedir(), '.codex', 'skills'),
-        join(homedir(), '.agents', 'skills'),
-        join(process.cwd(), 'skills'),
-    ]
-        .filter((value) => Boolean(value))
-        .map(value => value.endsWith('browser-worker.agent.md')
-        ? value
-        : join(value, 'chatgpt-browser-worker', 'agents', 'browser-worker.agent.md'));
-}
-async function loadBrowserWorkerRuntime(explicit) {
-    for (const candidate of browserWorkerCandidates(explicit)) {
-        try {
-            await access(candidate);
-            return { definition: await readFile(candidate, 'utf8'), root: dirname(dirname(candidate)) };
-        }
-        catch {
-            // Try the next installed skill root.
-        }
+async function loadBrowserWorkerRuntime(context, explicit) {
+    const resolvedSkill = context?.skills.find(skill => skill.name === 'chatgpt-browser-worker');
+    // Once a worker receives a resolved execution context, that context owns
+    // skill discovery. The explicit path remains the fallback for direct
+    // adapter use, where no shared context has been resolved yet.
+    const candidate = resolvedSkill
+        ? join(dirname(resolvedSkill.path), 'agents', 'browser-worker.agent.md')
+        : explicit;
+    if (!candidate)
+        throw new Error('chatgpt-browser-worker is not visible in the resolved execution context');
+    try {
+        await access(candidate);
+        return { definition: await readFile(candidate, 'utf8'), root: dirname(dirname(candidate)) };
+    }
+    catch {
+        throw new Error(`chatgpt-browser-worker agent definition not found at resolved path: ${candidate}`);
     }
-    throw new Error('chatgpt-browser-worker agent definition not found; set AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT');
 }
 function parseDriverJson(output) {
     const lines = output.trim().split(/\r?\n/).filter(Boolean);
@@ -260,7 +248,7 @@ export class ChatGptAdapter {
         execution.launched = new Promise((resolve, reject) => { launchResolve = resolve; launchReject = reject; });
         execution.launched.catch(() => { });
         execution.promise = (async () => {
-            const runtime = await loadBrowserWorkerRuntime(this.agentPath);
+            const runtime = await loadBrowserWorkerRuntime(context.executionContext, this.agentPath);
             if (controller.signal.aborted)
                 throw new Error('browser-worker execution aborted');
             const policy = chatGptTabClosePolicy(task.chatgptTabClosePolicy, this.tabClosePolicy);

package/dist/cli.js

@@ -14,9 +14,11 @@ import { NatsEventBus, eventFor } from './events.js';
 import { serveDashboard } from './dashboard.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { discoverAgents } from './registry.js';
-import { AgentObjectivePlanner, CommandObjectivePlanner } from './planner.js';
+import { AgentObjectivePlanner, CommandObjectivePlanner, orchestratorPlanningDecision } from './planner.js';
 import { extendRetryBudget } from './scheduler.js';
-const usage = 'agents-relay <job|task|init|submit|record|agent-register|agent-discover|status|reconcile|retry|cancel|serve> [options]';
+import { resolveExecutionContext } from './execution-context.js';
+import { defaultWorkspaceRoot, resolveManagedProjectPath } from './workspace.js';
+const usage = 'agents-relay <job|task|context|init|submit|record|agent-register|agent-discover|status|reconcile|retry|cancel|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -26,6 +28,7 @@ Usage:
 Commands:
   job create|adopt|repair  Create or repair a durable GitHub-backed job
   task update              Update mutable durable task fields in place
+  context resolve          Resolve shared project instructions, skills, agents, and runtimes
   init                     Create a local demo job or initialize a GitHub job
   submit                   Queue a task for a managed job
   record                   Backfill a completed task into durable history
@@ -96,6 +99,21 @@ Use --clear-routing to remove routing metadata. A model update requires --model;
 
 Example:
   npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id build --adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high`,
+    context: `Resolve the shared execution context used by XChat and Relay.
+
+Usage:
+  npx agents-relay context resolve --project-path PATH --role ROLE [options]
+
+Actions:
+  resolve  Resolve instructions, visible skills/agents, and runtime/delegation metadata`,
+    'context resolve': `Resolve shared execution context without creating durable state.
+
+Required: --project-path PATH.
+Common: --role orchestrator|planner|reviewer|worker|nested-worker, --skills a,b, --agents a,b.
+Root overrides for testing/configuration: --workspace-root PATH, --neo-root PATH|none, --global-root PATH.
+
+Example:
+  npx agents-relay context resolve --project-path ~/Workspace/agents-relay --role orchestrator`,
     submit: `Queue a task for a managed job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, --id JOB_ID, and --input TEXT.
@@ -167,6 +185,8 @@ export function helpText(command, action) {
         return action ? help[`job ${action}`] ?? help.job : help.job;
     if (command === 'task')
         return action ? help[`task ${action}`] ?? help.task : help.task;
+    if (command === 'context')
+        return action ? help[`context ${action}`] ?? help.context : help.context;
     return command ? help[command] ?? help.root : help.root;
 }
 export const SERVICE_DEFAULTS = { port: 8787, watchdogMs: 300000, webhookWatchdogMs: 1800000, dashboardRefreshMs: 300000 };
@@ -250,7 +270,7 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         if (!(error instanceof Error) || !error.message.includes('has no durable'))
             throw error;
         const now = new Date().toISOString();
-        job = { id: options.id, title: options.title || pr.title || 'Agents Relay job', objective: options.objective || pr.body || undefined, description: pr.body || undefined, priority: options.priority ?? 'P2', executionMode: options.executionMode ?? 'fixed', autoMerge: options.autoMerge ?? true, prNumber: pr.number, repository: repositoryName, state: 'OPEN', continuation: options.continuation ?? null, createdAt: now, updatedAt: now, tasks: [] };
+        job = { id: options.id, title: options.title || pr.title || 'Agents Relay job', objective: options.objective || pr.body || undefined, description: pr.body || undefined, priority: options.priority ?? 'P2', executionMode: options.executionMode ?? 'fixed', autoMerge: options.autoMerge ?? true, prNumber: pr.number, repository: repositoryName, state: 'OPEN', continuation: options.continuation ?? null, initialPlanning: options.initialTasks?.length ? { status: 'pending', decisionId: 'planner-0' } : undefined, createdAt: now, updatedAt: now, tasks: [] };
     }
     if (!job.description && pr.body)
         job.description = pr.body;
@@ -266,9 +286,40 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         job.priority = 'P2';
     if (!job.title && pr.title)
         job.title = pr.title;
-    await store.saveJob(job);
+    if (options.initialTasks?.length) {
+        const decisionId = job.initialPlanning?.decisionId ?? 'planner-0';
+        job.initialPlanning = { status: 'pending', decisionId };
+        job.updatedAt = new Date().toISOString();
+        await store.saveJob(job);
+        const decision = orchestratorPlanningDecision(job, options.initialTasks, decisionId, null, 0);
+        if (!(await store.load(options.id)).tasks.some(task => task.id === decision.id))
+            await store.appendTask(decision);
+        for (const original of options.initialTasks) {
+            const task = { ...original, parentTaskId: decision.id, planningDecisionId: decision.id, planningSource: 'orchestrator', planningRound: 0 };
+            if (!(await store.load(options.id)).tasks.some(item => item.id === task.id))
+                await store.appendTask(task);
+        }
+        job.initialPlanning = { status: 'complete', decisionId };
+        job.updatedAt = new Date().toISOString();
+        await store.saveJob(job);
+    }
+    else
+        await store.saveJob(job);
     return { job: await store.load(options.id), pr };
 }
+async function appendPlannedTask(store, job, task) {
+    const existing = job.tasks.find(item => item.id === task.id);
+    if (existing)
+        return existing;
+    const decisionId = `plan-${task.id}`;
+    const decision = orchestratorPlanningDecision(job, [task], decisionId, task.parentTaskId, job.tasks.filter(item => item.kind === 'planner').length, 'orchestrator');
+    if (!job.tasks.some(item => item.id === decision.id))
+        await store.appendTask(decision);
+    const planned = { ...task, parentTaskId: task.parentTaskId ?? null, planningDecisionId: decision.id, planningSource: 'orchestrator', planningRound: decision.planningRound };
+    await store.appendTask(planned);
+    job.tasks.push(planned, decision);
+    return planned;
+}
 function workerTaskFromArgs(job, args, now, requireInput = false) {
     const model = arg(args, '--model');
     const adapterValue = arg(args, '--adapter');
@@ -390,6 +441,26 @@ async function runTaskCommand(action, args) {
     await saveLocal(localFile, job);
     console.log(JSON.stringify(task, null, 2));
 }
+async function runContextCommand(action, args) {
+    if (action !== 'resolve')
+        throw new Error(usage);
+    const projectPath = arg(args, '--project-path');
+    if (!projectPath)
+        throw new Error('context resolve requires --project-path');
+    const roleValue = arg(args, '--role', 'orchestrator');
+    const roles = ['orchestrator', 'planner', 'reviewer', 'worker', 'nested-worker'];
+    if (!roles.includes(roleValue))
+        throw new Error('--role must be orchestrator, planner, reviewer, worker, or nested-worker');
+    const neoRootArg = arg(args, '--neo-root');
+    const context = await resolveExecutionContext(projectPath, roleValue, {
+        workspaceRoot: arg(args, '--workspace-root') || undefined,
+        neoRoot: neoRootArg === 'none' ? null : neoRootArg || undefined,
+        globalRoot: arg(args, '--global-root') || undefined,
+        explicitSkills: arg(args, '--skills').split(',').filter(Boolean),
+        explicitAgents: arg(args, '--agents').split(',').filter(Boolean),
+    });
+    console.log(JSON.stringify(context, null, 2));
+}
 async function runJobCommand(action, args) {
     if (!['create', 'adopt', 'repair'].includes(action))
         throw new Error(usage);
@@ -398,12 +469,12 @@ async function runJobCommand(action, args) {
     if (!id)
         throw new Error('--id is required for managed GitHub jobs');
     const start = hasArg(args, '--start');
+    const initialTask = start ? workerTaskFromArgs({ id, title: '', executionMode: 'fixed', prNumber: 0, repository: repo, state: 'OPEN', continuation: null, createdAt: '', updatedAt: '', tasks: [] }, args, new Date().toISOString(), true) : undefined;
     if (start && action !== 'create')
         throw new Error('--start is only supported by job create');
     if (start) {
         if (!hasArg(args, '--adapter'))
             throw new Error('job create --start requires --adapter codex|chatgpt');
-        workerTaskFromArgs({ id, title: '', executionMode: 'fixed', prNumber: 0, repository: repo, state: 'OPEN', continuation: null, createdAt: '', updatedAt: '', tasks: [] }, args, new Date().toISOString(), true);
     }
     const auth = await githubAuthContext(args);
     const client = auth.client;
@@ -425,23 +496,16 @@ async function runJobCommand(action, args) {
         prNumber,
         head: arg(args, '--head') || undefined,
         base: arg(args, '--base', 'main'),
-        body: arg(args, '--body') || undefined
+        body: arg(args, '--body') || undefined,
+        initialTasks: initialTask ? [initialTask] : undefined
     });
-    if (start) {
-        const task = workerTaskFromArgs(result.job, args, new Date().toISOString(), true);
-        const existing = result.job.tasks.find(item => item.id === task.id);
-        const store = new GitHubStore(client, repo, result.pr.number, trustedAuthors);
-        await store.appendTask(task);
-        if (!existing) {
-            await publishWake(eventBus(args), result.job, task.id, `Task ${task.id} submitted`);
-            result.job.tasks.push(task);
-        }
-    }
+    if (start)
+        await publishWake(eventBus(args), result.job, initialTask?.id ?? 'initial', `Initial planning decision and task ${initialTask?.id ?? 'initial'} recorded`);
     console.log(JSON.stringify({ repository: repo, pr: result.pr.number, job: result.job.id, executionMode: result.job.executionMode, state: result.job.state, task: start ? arg(args, '--task-id', 'initial') : undefined }, null, 2));
 }
 export function runtimePlanner(args) { const plannerCommand = arg([...args], '--planner-command'); const modelRuntime = arg([...args], '--codex', 'codex'); return plannerCommand ? new CommandObjectivePlanner(plannerCommand) : new AgentObjectivePlanner(modelRuntime); }
 export function runtimeReviewer() { return { adapter: 'chatgpt', routing: { provider: 'chatgpt', model: 'account-defaults', decidedBy: 'fixed-chatgpt-reviewer', decidedAt: new Date().toISOString() } }; }
-export function runtime(store, args, bus) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const modelRuntime = arg(args, '--codex', 'codex'); const policy = chatGptTabClosePolicy(args); const planner = runtimePlanner(args); return new Reconciler(store, { owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, reviewer: runtimeReviewer(), eventBus: bus, emit, chatgptTabClosePolicy: policy }); }
+export function runtime(store, args, bus) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const modelRuntime = arg(args, '--codex', 'codex'); const policy = chatGptTabClosePolicy(args); const planner = runtimePlanner(args); return new Reconciler(store, { owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, reviewer: runtimeReviewer(), eventBus: bus, emit, chatgptTabClosePolicy: policy, projectPathForJob: job => resolveManagedProjectPath(job.repository, arg(args, '--project-path'), arg(args, '--workspace-root') || defaultWorkspaceRoot()) }); }
 export async function createService(args) {
     const loaded = await storeFor(args);
     const upstream = eventBus(args);
@@ -519,7 +583,7 @@ async function main() {
         return;
     }
     if (args.includes('--help') || args.includes('-h')) {
-        console.log(helpText(command, command === 'job' || command === 'task' ? args[0] : undefined));
+        console.log(helpText(command, command === 'job' || command === 'task' || command === 'context' ? args[0] : undefined));
         return;
     }
     if (command === 'job') {
@@ -532,6 +596,11 @@ async function main() {
         await runTaskCommand(action ?? '', taskArgs);
         return;
     }
+    if (command === 'context') {
+        const [action, ...contextArgs] = args;
+        await runContextCommand(action ?? '', contextArgs);
+        return;
+    }
     if (command === 'init') {
         const now = new Date().toISOString();
         const job = { id: arg(args, '--id', randomUUID()), title: arg(args, '--title', 'Agents Relay job'), objective: arg(args, '--objective') || undefined, priority: priority(args), executionMode: executionMode(args), autoMerge: !hasArg(args, '--no-auto-merge'), prNumber: Number(arg(args, '--pr', '0')), repository: arg(args, '--repo'), state: 'OPEN', continuation: continuation(args), createdAt: now, updatedAt: now, tasks: [] };
@@ -576,8 +645,7 @@ async function main() {
             throw new Error('record requires --summary');
         const commit = arg(args, '--commit');
         const task = { jobId: job.id, id, projectName: arg(args, '--project') || undefined, agentName: arg(args, '--agent', 'orchestrator'), parentTaskId: arg(args, '--parent') || null, dependencies: arg(args, '--deps').split(',').filter(Boolean), capabilities: [], adapter: 'orchestrator', input: arg(args, '--input', summary), continuation: null, continuationDeliveredAt: null, state: 'SUCCEEDED', attempt: 1, maxAttempts: 1, leaseOwner: null, leaseExpiresAt: null, executionId: commit || null, threadId: null, result: { summary, data: commit ? { commit } : undefined }, error: null, timeoutMs: 0, createdAt: now, updatedAt: now };
-        await store.appendTask(task);
-        job.tasks.push(task);
+        await appendPlannedTask(store, job, task);
         await saveLocal(localFile, job);
         console.log(`Recorded ${id}`);
         return;
@@ -586,16 +654,15 @@ async function main() {
         const now = new Date().toISOString();
         const task = workerTaskFromArgs(job, args, now);
         task.id = arg(args, '--task-id', randomUUID());
-        await store.appendTask(task);
-        job.tasks.push(task);
+        const planned = await appendPlannedTask(store, job, task);
         if (job.state !== 'RUNNING') {
             job.state = 'RUNNING';
             job.updatedAt = now;
             await store.saveJob(job);
         }
         await saveLocal(localFile, job);
-        await publishWake(bus, job, task.id, `Task ${task.id} submitted`);
-        console.log(`Submitted ${task.id}`);
+        await publishWake(bus, job, planned.id, `Planning decision recorded and task ${planned.id} submitted`);
+        console.log(`Submitted ${planned.id}`);
         return;
     }
     if (command === 'status') {

package/dist/dashboard.js

@@ -240,7 +240,7 @@ function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();
 function taskNode(task,children,depth){const li=element('li');const row=document.createElement('button');row.type='button';row.className='task-row';row.setAttribute('aria-current',String(task.id===selectedTaskId));row.title=task.id;row.addEventListener('click',()=>{selectedTaskId=task.id;eventTaskId=task.id;rememberSelection();clearEvents();renderAll();void loadEventHistory();});const id=element('span','task-id',text(task.id));id.style.paddingLeft=Math.min(depth,4)*6+'px';row.append(id,element('span','badge '+value(task.state),text(task.state)));li.append(row);const nested=children.get(task.id)||[];if(nested.length){const ul=element('ul','tree');for(const child of nested)ul.append(taskNode(child,children,depth+1));li.append(ul);}return li;}
 function buildTree(tasks){taskTree.replaceChildren();if(!Array.isArray(tasks)||!tasks.length){taskTree.append(element('li','empty',text('No tasks in durable state.')));return;}const known=new Set(tasks.map(task=>task.id));const children=new Map();const roots=[];for(const task of tasks){if(!task.parentTaskId||!known.has(task.parentTaskId))roots.push(task);else{const siblings=children.get(task.parentTaskId)||[];siblings.push(task);children.set(task.parentTaskId,siblings);}}for(const task of roots)taskTree.append(taskNode(task,children,0));}
 function attemptBudget(task){const attempt=Number(task?.attempt)||0;const max=Number(task?.maxAttempts)||0;if(max>=3&&max%3===0){const effectiveMax=Math.max(max,Math.ceil(attempt/3)*3);return attempt+' / 3×'+(effectiveMax/3);}return attempt+' / '+max;}
-function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const routing=task.routing||{};const groups=element('div','detail-groups');groups.append(field('Task',task.id),field('Kind',task.kind||'work'),field('State',task.state),field('Project / agent',value(task.projectName)+' / '+value(task.agentName)),field('Parent task',task.parentTaskId||'root'),field('Adapter',task.adapter),field('Provider / model',value(routing.provider)+' / '+value(routing.model)),field('Reasoning / profile',value(routing.reasoning||routing.profile)),field('Attempt',attemptBudget(task)),field('Dependencies',Array.isArray(task.dependencies)&&task.dependencies.length?task.dependencies.join(', '):'none'),chatField(task));if(task.plannerResult)groups.append(field('Objective status',task.plannerResult.objective_status),markdownField('Assessment',task.plannerResult.assessment));if(task.error)groups.append(field('Error',task.error));taskDetailRoot.append(groups);}
+function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const routing=task.routing||{};const groups=element('div','detail-groups');groups.append(field('Task',task.id),field('Kind',task.kind||'work'),field('State',task.state),field('Planning decision',task.planningDecisionId||'—'),field('Planning source',task.planningSource||'—'),field('Planning round',task.planningRound===undefined?'—':String(task.planningRound)),field('Project / agent',value(task.projectName)+' / '+value(task.agentName)),field('Parent task',task.parentTaskId||'root'),field('Adapter',task.adapter),field('Provider / model',value(routing.provider)+' / '+value(routing.model)),field('Reasoning / profile',value(routing.reasoning||routing.profile)),field('Attempt',attemptBudget(task)),field('Dependencies',Array.isArray(task.dependencies)&&task.dependencies.length?task.dependencies.join(', '):'none'),chatField(task));if(task.plannerResult)groups.append(field('Objective status',task.plannerResult.objective_status),markdownField('Assessment',task.plannerResult.assessment));if(task.error)groups.append(field('Error',task.error));taskDetailRoot.append(groups);}
 function reviewStatus(job){const review=job?.review;if(!review)return 'Not started';if(review.outcome==='approved'&&review.headSha===job.headSha)return 'MERGE READY · approved';const stale=Array.isArray(job?.tasks)&&job.tasks.some(task=>task.agentName==='reviewer'&&task.reviewHeadSha&&job.headSha&&task.reviewHeadSha!==job.headSha);if(stale)return 'STALE · awaiting review';return String(review.outcome||'pending').replace('_',' ').toUpperCase();}
 function renderSelectedJob(){jobDetail.replaceChildren();const job=selected();if(!job){selectedJobTitle.textContent='';jobDetail.append(element('div','empty',text('No durable jobs discovered.')));buildTree([]);renderTaskDetail(null);return;}selectedJobTitle.textContent='— '+value(job.title||job.id);if(job.id!==selectedJob){selectedJob=job.id;selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}const summary=element('div','job-summary');summary.append(field('GitHub state',job.githubState||'UNKNOWN'),field('Durable state',job.state),field('Execution mode',job.executionMode||'fixed'),field('Status',awaitingInitialTask(job)?'Awaiting initial task':job.state),field('Review',reviewStatus(job)),field('Review head SHA',job.review?.headSha||job.headSha||'—'),field('Objective',job.objective||job.description||job.title),prField(job),field('Repository',job.repository||'—'),field('Last activity',relativeTime(job.updatedAt)),field('Task states',compactCounts(job.tasks)));jobDetail.append(summary);const selectedTask=(job.tasks||[]).find(task=>task.id===selectedTaskId)||null;if(selectedTaskId&&!selectedTask){selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}buildTree(job.tasks||[]);renderTaskDetail(selectedTask);renderEventScope();}
 function renderAll(){jobs.sort(compareJobs);syncFilters();renderJobList();renderSelectedJob();}

package/dist/execution-context.js

@@ -0,0 +1,258 @@
+import { access, readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isWithin(path, root) {
+    const value = relative(root, path);
+    return value === '' || (!value.startsWith('..' + sep) && value !== '..' && !isAbsolute(value));
+}
+async function directory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function configuredWorkspaceRoot(projectPath, explicit) {
+    const configured = explicit ?? process.env.AGENTS_RELAY_WORKSPACE_ROOT ?? process.env.XCHAT_WORKSPACE_ROOT;
+    if (configured)
+        return resolve(configured);
+    const conventional = join(homedir(), 'Workspace');
+    return isWithin(projectPath, conventional) ? conventional : dirname(projectPath);
+}
+async function configuredNeoRoot(workspaceRoot, explicit) {
+    if (explicit === null)
+        return null;
+    const configured = explicit ?? process.env.NEO_SHARED_ROOT;
+    if (configured)
+        return await directory(resolve(configured)) ? await realpath(resolve(configured)) : null;
+    const candidate = join(workspaceRoot, 'neo');
+    return await directory(candidate) ? await realpath(candidate) : null;
+}
+function configuredGlobalRoot(explicit) {
+    return resolve(explicit ?? process.env.AGENTS_HOME ?? join(homedir(), '.agents'));
+}
+function parseFrontmatter(content) {
+    if (!content.startsWith('---\n'))
+        return {};
+    const end = content.indexOf('\n---', 4);
+    if (end < 0)
+        return {};
+    const result = {};
+    for (const line of content.slice(4, end).split(/\r?\n/)) {
+        const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!match)
+            continue;
+        result[match[1]] = match[2].trim().replace(/^['"]|['"]$/g, '');
+    }
+    return result;
+}
+function listValue(value) {
+    if (!value)
+        return [];
+    const trimmed = value.trim();
+    const body = trimmed.startsWith('[') && trimmed.endsWith(']') ? trimmed.slice(1, -1) : trimmed;
+    return body.split(/[|,]/).map(item => item.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+}
+async function metadata(path) {
+    const content = await readFile(path, 'utf8');
+    return { fields: parseFrontmatter(content), content };
+}
+async function instructionPaths(projectPath, workspaceRoot, neoRoot, globalRoot) {
+    const found = [];
+    const add = async (path, source) => {
+        if (await exists(path)) {
+            const concrete = await realpath(path);
+            if (!found.some(item => item.path === concrete))
+                found.push({ path: concrete, source });
+        }
+    };
+    await add(join(globalRoot, 'AGENTS.md'), 'global');
+    if (isWithin(projectPath, workspaceRoot)) {
+        const segments = relative(workspaceRoot, projectPath).split(sep).filter(Boolean);
+        let cursor = workspaceRoot;
+        await add(join(cursor, 'AGENTS.md'), neoRoot && isWithin(cursor, neoRoot) ? 'neo' : 'project');
+        for (const segment of segments) {
+            cursor = join(cursor, segment);
+            const source = neoRoot && isWithin(cursor, neoRoot) && !isWithin(cursor, projectPath) ? 'neo' : 'project';
+            await add(join(cursor, 'AGENTS.md'), source);
+        }
+    }
+    else {
+        await add(join(projectPath, 'AGENTS.md'), 'project');
+    }
+    await add(join(projectPath, 'README.md'), 'project');
+    return found;
+}
+async function skillLayer(root, source) {
+    const skillsRoot = join(root, 'skills');
+    let entries;
+    try {
+        entries = await readdir(skillsRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const result = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const path = join(skillsRoot, entry.name, 'SKILL.md');
+        if (!await exists(path))
+            continue;
+        const { fields } = await metadata(path);
+        result.push({ name: fields.name || entry.name, path: await realpath(path), source, description: fields.description || undefined });
+    }
+    return result.sort((a, b) => a.name.localeCompare(b.name));
+}
+async function agentFiles(root, source, skills) {
+    const candidates = [];
+    const skillDirs = skills.filter(skill => skill.source === source).map(skill => dirname(skill.path));
+    for (const skillDir of skillDirs) {
+        let entries;
+        try {
+            entries = await readdir(join(skillDir, 'agents'), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries)
+            if (entry.isFile() && entry.name.endsWith('.md'))
+                candidates.push(join(skillDir, 'agents', entry.name));
+    }
+    let direct;
+    try {
+        direct = await readdir(join(root, 'agents'), { withFileTypes: true });
+    }
+    catch {
+        direct = [];
+    }
+    for (const entry of direct)
+        if (entry.isFile() && entry.name.endsWith('.md'))
+            candidates.push(join(root, 'agents', entry.name));
+    const result = [];
+    for (const path of candidates) {
+        const { fields } = await metadata(path);
+        result.push({
+            name: fields.name || basename(path).replace(/\.agent\.md$/i, '').replace(/\.md$/i, ''),
+            path: await realpath(path),
+            source,
+            description: fields.description || undefined,
+            capabilities: listValue(fields.capabilities),
+            runtime: fields.runtime || listValue(fields.runtimes)[0] || undefined,
+            trustDomains: listValue(fields.trustDomains ?? fields.trust_domains ?? fields.trust),
+            delegation: listValue(fields.delegation),
+            restrictions: listValue(fields.restrictions ?? fields.boundaries),
+        });
+    }
+    return result;
+}
+function selectByName(items, explicit, kind) {
+    if (!explicit?.length)
+        return [...items];
+    const selected = explicit.map(name => {
+        const item = items.find(candidate => candidate.name === name);
+        if (!item)
+            throw new Error(`Explicit ${kind} ${name} is not visible in the resolved execution context`);
+        return item;
+    });
+    return selected;
+}
+export async function resolveExecutionContext(projectPath, role, options = {}) {
+    if (!projectPath)
+        throw new Error('projectPath is required');
+    const project = await realpath(resolve(projectPath)).catch(() => { throw new Error(`Project path not found: ${projectPath}`); });
+    if (!await directory(project))
+        throw new Error(`Project path is not a directory: ${projectPath}`);
+    const workspaceCandidate = configuredWorkspaceRoot(project, options.workspaceRoot);
+    const workspaceRoot = await realpath(workspaceCandidate).catch(() => workspaceCandidate);
+    const neoRoot = await configuredNeoRoot(workspaceRoot, options.neoRoot);
+    const globalCandidate = configuredGlobalRoot(options.globalRoot);
+    const globalRoot = await realpath(globalCandidate).catch(() => globalCandidate);
+    const layerRoots = [
+        { root: globalRoot, source: 'global' },
+        ...(neoRoot ? [{ root: neoRoot, source: 'neo' }] : []),
+        { root: project, source: 'project' },
+    ];
+    const uniqueLayers = layerRoots.filter((layer, index, list) => list.findIndex(item => resolve(item.root) === resolve(layer.root)) === index);
+    const skillMap = new Map();
+    const skillsByLayer = new Map();
+    for (const layer of uniqueLayers) {
+        const layerSkills = await skillLayer(layer.root, layer.source);
+        skillsByLayer.set(layer.root, layerSkills);
+        for (const skill of layerSkills)
+            skillMap.set(skill.name, skill);
+    }
+    const skills = selectByName([...skillMap.values()].sort((a, b) => a.name.localeCompare(b.name)), options.explicitSkills, 'skill');
+    const agentMap = new Map();
+    for (const layer of uniqueLayers) {
+        for (const agent of await agentFiles(layer.root, layer.source, skillsByLayer.get(layer.root) ?? []))
+            agentMap.set(agent.name, agent);
+    }
+    for (const registration of options.registeredAgents ?? []) {
+        if (agentMap.has(registration.name))
+            continue;
+        agentMap.set(registration.name, {
+            name: registration.name,
+            source: 'registry',
+            description: registration.responsibility,
+            capabilities: [...registration.capabilities],
+            runtime: registration.runtime.adapter,
+            trustDomains: [...(registration.routing.trustDomains ?? [])],
+            delegation: [],
+            restrictions: [...registration.boundaries],
+            registration,
+        });
+    }
+    const agents = selectByName([...agentMap.values()].sort((a, b) => a.name.localeCompare(b.name)), options.explicitAgents, 'agent');
+    return {
+        project: { name: basename(project), path: project, workspaceRoot, neoRoot, globalRoot },
+        role,
+        instructions: await instructionPaths(project, workspaceRoot, neoRoot, globalRoot),
+        skills,
+        agents,
+        runtimes: (options.runtimes ?? []).map(runtime => ({ name: runtime.name ?? runtime.adapter ?? 'unknown', id: runtime.id, capabilities: [...runtime.capabilities], source: 'runtime' })),
+        delegation: { mode: 'relay-child-task', parentTaskIdRequired: role === 'nested-worker' },
+    };
+}
+export function executionContextPrompt(context) {
+    const instructions = context.instructions.map(item => `- ${item.path} [${item.source}]`).join('\n') || '- none';
+    const skills = context.skills.map(item => `- ${item.name}: ${item.path} [${item.source}]`).join('\n') || '- none';
+    const agents = context.agents.map(item => {
+        const details = [
+            item.capabilities.length ? `capabilities=${item.capabilities.join(',')}` : '',
+            item.runtime ? `runtime=${item.runtime}` : '',
+            item.trustDomains.length ? `trust=${item.trustDomains.join(',')}` : '',
+            item.restrictions.length ? `restrictions=${item.restrictions.join(' | ')}` : '',
+        ].filter(Boolean).join('; ');
+        return `- ${item.name}${item.path ? `: ${item.path}` : ''} [${item.source}]${details ? ` — ${details}` : ''}`;
+    }).join('\n') || '- none';
+    const runtimes = context.runtimes.map(item => `- ${item.name}${item.id ? ` (${item.id})` : ''}: ${item.capabilities.join(',')}`).join('\n') || '- none';
+    return `[Resolved execution context]
+Role: ${context.role}
+Project path: ${context.project.path}
+
+Instructions (read in listed order; later/project-local instructions override earlier shared defaults):
+${instructions}
+
+Visible skills (already de-duplicated with project-local > Neo shared > global precedence):
+${skills}
+
+Visible agents:
+${agents}
+
+Runtime capabilities:
+${runtimes}
+
+Delegation contract:
+Nested work MUST be created as an Agents Relay durable child task with parentTaskId lineage. Do not directly spawn arbitrary child agents. Leaf workers do not inherit top-level XChat orchestration duties merely because xchat-orchestrator is visible.`;
+}