@qodeca/xezar 0.13.1 → 0.14.0

package/dist/mcp/tools/discovery.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { type HealthResponse, type McpDiscovery, type McpDiscoveryLimits, type ProviderStatusResponse } from '../../contract/index.js';
+import { type McpToolContext } from '../tool.ts';
+/**
+ * `discover_project` (#90, F-03, U-M06): which project this session is bound to, what it can do
+ * and within which limits, and — for everything it cannot do — why.
+ *
+ * Two halves on purpose. `collectDiscoveryFacts` gathers what `GET /health` and `GET /config`
+ * report, through the same helpers those routes call, for the BOUND project only: it never reads
+ * the project list at all. `buildDiscovery` is the filter — pure, and the part the isolation
+ * guarantees rest on. It accepts the health shape (a full `HealthResponse` included, `projects`
+ * and `bootProject` and all), copies out only what `mcpDiscoverySchema` names, and writes every
+ * reason itself instead of forwarding a CLI's text: raw `gh` or agent output can name an account
+ * or an organisation (F-12, F-15). The strict schema parse at the end turns any key that slips in
+ * later into a tool failure instead of a leak.
+ */
+export interface DiscoveryFacts {
+    project: McpToolContext['project'];
+    xezarVersion: string;
+    /** Structurally a subset of `HealthResponse`, so a whole health payload is accepted — and filtered. */
+    health: Pick<HealthResponse, 'repo' | 'checks' | 'forge' | 'capabilities' | 'defaultRunner'>;
+    config: {
+        baseBranch: string | null;
+        modelsLocked: boolean;
+    };
+    providers: ProviderStatusResponse;
+    limits: McpDiscoveryLimits;
+}
+export declare function buildDiscovery(facts: DiscoveryFacts): McpDiscovery;
+/**
+ * `--bind-host` of THIS process. The MCP socket lives inside `xezar serve`, and a non-loopback
+ * bind is half of what makes the cockpit hosted; `McpToolContext` does not carry it yet (#89
+ * widens that context), and reporting `localHandoff: true` on a hosted box would promise actions
+ * the routes refuse.
+ */
+export declare function bindHostFromArgv(argv?: readonly string[]): string | undefined;
+export declare function collectDiscoveryFacts(ctx: McpToolContext, env?: NodeJS.ProcessEnv): Promise<DiscoveryFacts>;
+/** The authoritative text block (D-05): a one-line orientation, then the whole result. */
+export declare function discoveryText(discovery: McpDiscovery): string;
+export declare const discoverProjectTool: import("../tool.ts").McpTool<z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>;

package/dist/mcp/tools/discovery.js

@@ -0,0 +1,232 @@
+import { basename } from 'node:path';
+import { z } from 'zod';
+import { mcpDiscoverySchema, } from '../../contract/index.js';
+import { loadConfig } from '../../config.js';
+import { agentModelsLocked } from '../../core/agent-model-policy.js';
+import { ProviderAuthService } from '../../core/provider-auth.js';
+import { applyProviderEnablement } from '../../core/provider-availability.js';
+import { detectEnvironment } from '../../core/backend-detect.js';
+import { resolveCapabilities } from '../../server/capabilities.js';
+import { resolveForge } from '../../server/forge/index.js';
+import { getRepoInfo } from '../../server/git.js';
+import { loadWorkspaceConfig } from '../../workspace/config.js';
+import { defineTool, textResult } from '../tool.js';
+const RUNNERS = ['claude', 'codex', 'opencode', 'pi'];
+const LABEL = { claude: 'Claude Code', codex: 'Codex', opencode: 'OpenCode', pi: 'pi' };
+const PROVIDERS_SETTINGS = 'Settings → Agents → Providers';
+const HOSTED_REASON = 'This xezar runs in hosted mode (XEZ_REMOTE=1 or a non-loopback bind), so actions on the host machine are refused.';
+export function buildDiscovery(facts) {
+    const { health, config } = facts;
+    const caps = health.capabilities;
+    const agents = RUNNERS.map((runner) => agentEntry(runner, facts));
+    const git = health.repo !== null;
+    const githubReason = githubUnavailableReason(facts);
+    const actions = [
+        action('create_task', 'Start a task', createTaskReason(agents)),
+        action('parallel_variants', 'Run a task as parallel variants', git ? null : 'Parallel variants need a git repository — each variant runs in its own worktree.'),
+        action('worktree_choice', 'Choose worktree or in-place for a task', git ? null : 'This project is not a git repository, so tasks run in place, one at a time.'),
+        config.modelsLocked
+            ? readOnly('model_selection', 'Choose a task model', "Models are locked: each coding agent uses the model from its own native settings. Only a person can change that (XEZ_AGENT_MODELS_LOCKED or modelsLocked in xezar's config).")
+            : action('model_selection', 'Choose a task model', null),
+        action('github', 'GitHub issues, pull requests and draft PRs', githubReason),
+        action('automations', 'GitHub automations', !caps.automations
+            ? 'GitHub automations are off on this xezar. A person can start it with XEZ_AUTOMATIONS=1 to turn them on.'
+            : githubReason && `GitHub automations need GitHub: ${githubReason}`),
+        action('inbox', 'Follow-up inbox', caps.followups
+            ? null
+            : 'The follow-up inbox is off for this workspace. A person can turn it on in the cockpit settings (or with XEZ_FOLLOWUPS=1).'),
+        action('open_in_app', 'Open the project or a task in a desktop app', caps.localHandoff ? null : HOSTED_REASON),
+        action('agent_config_write', "Edit the coding agents' config files", caps.localHandoff ? null : `${HOSTED_REASON} Agent config files can define hooks and commands, so they are never written remotely.`),
+        readOnly('workspace_limits', 'Change workspace-wide limits', "Workspace limits are shared with every project. The leader can read them; only a person can change them in the cockpit's global settings."),
+    ];
+    return mcpDiscoverySchema.parse({
+        project: {
+            id: facts.project.id,
+            name: facts.project.name,
+            // The rule `/health` already follows (#431): a hosted cockpit reports a basename only.
+            root: caps.localHandoff ? facts.project.root : basename(facts.project.root),
+        },
+        xezarVersion: facts.xezarVersion,
+        repository: git ? { git: true, branch: health.repo.branch } : { git: false },
+        settings: { defaultRunner: health.defaultRunner, baseBranch: config.baseBranch, modelsLocked: config.modelsLocked },
+        capabilities: { localHandoff: caps.localHandoff, followups: caps.followups, automations: caps.automations },
+        agents,
+        tools: ['gh', 'git'].map((name) => toolCheck(name, facts)),
+        limits: facts.limits,
+        actions,
+    });
+}
+function action(id, label, reason) {
+    return reason ? { id, label, status: 'unavailable', reason } : { id, label, status: 'available' };
+}
+function readOnly(id, label, reason) {
+    return { id, label, status: 'read-only', reason };
+}
+function agentEntry(runner, facts) {
+    const check = facts.health.checks.find((c) => c.name === runner);
+    const row = facts.providers.providers.find((p) => p.provider === runner);
+    const signIn = row?.status ?? 'unknown';
+    const installed = check ? check.available : signIn !== 'not-installed';
+    const enabled = row?.enabled !== false;
+    // The cockpit's own rule (`usableRunners`): enabled AND signed in.
+    const usable = enabled && signIn === 'connected';
+    const version = installed ? versionLine(check?.version) : undefined;
+    return {
+        runner,
+        installed,
+        ...(version ? { version } : {}),
+        enabled,
+        signIn,
+        usable,
+        ...(usable ? {} : { reason: agentReason(runner, enabled, installed ? signIn : 'not-installed') }),
+    };
+}
+function agentReason(runner, enabled, signIn) {
+    const label = LABEL[runner];
+    if (!enabled)
+        return `${label} is disabled in ${PROVIDERS_SETTINGS}.`;
+    switch (signIn) {
+        case 'not-installed':
+            return `${label} is not installed on this machine.`;
+        case 'disconnected':
+            return `${label} is installed but not signed in. A person can sign in from ${PROVIDERS_SETTINGS}.`;
+        default:
+            return `${label}'s sign-in could not be verified yet. Call this tool again shortly.`;
+    }
+}
+/** A version is one short line of a CLI's `--version`; anything longer is not a version. */
+function versionLine(version) {
+    const line = version?.split('\n')[0]?.trim();
+    return line ? line.slice(0, 80) : undefined;
+}
+function createTaskReason(agents) {
+    if (agents.some((a) => a.usable))
+        return null;
+    return `No coding agent is ready to run a task. ${agents.map((a) => a.reason).join(' ')}`;
+}
+function toolCheck(name, facts) {
+    const available = facts.health.checks.find((c) => c.name === name)?.available === true;
+    if (available)
+        return { name, available };
+    return {
+        name,
+        available,
+        reason: name === 'gh'
+            ? 'The GitHub CLI (gh) is not installed or not signed in. GitHub features need it; a person can run `gh auth login`.'
+            : 'git is not installed on this machine.',
+    };
+}
+/**
+ * Why the GitHub area is closed, or null when it is open. `gh`'s own error text is CLASSIFIED,
+ * never forwarded: it can quote the repository owner, an organisation or an account.
+ */
+function githubUnavailableReason(facts) {
+    const { repo, forge } = facts.health;
+    if (!repo)
+        return 'This project is not a git repository, so it has no GitHub remote.';
+    if (!forge)
+        return "This repository has no GitHub remote; xezar's GitHub features need a github.com remote.";
+    if (forge.available === true)
+        return null;
+    if (forge.available === undefined) {
+        return 'GitHub availability has not been checked yet. Call this tool again in a few seconds.';
+    }
+    const raw = forge.reason ?? '';
+    if (/ENOENT|gh CLI not found/i.test(raw)) {
+        return 'The GitHub CLI (gh) is not installed on this machine. A person can install it and run `gh auth login`.';
+    }
+    if (/auth login|not logged|authenticat|credential|\b401\b/i.test(raw)) {
+        return 'The GitHub CLI (gh) is not signed in. A person can run `gh auth login`.';
+    }
+    return 'The GitHub CLI (gh) could not open this repository on GitHub. Check `gh auth status`, access to the repository and the network.';
+}
+// ---- gathering: the same facts `/health` and `/config` read, for the bound project only ------
+let providerAuth;
+/**
+ * `--bind-host` of THIS process. The MCP socket lives inside `xezar serve`, and a non-loopback
+ * bind is half of what makes the cockpit hosted; `McpToolContext` does not carry it yet (#89
+ * widens that context), and reporting `localHandoff: true` on a hosted box would promise actions
+ * the routes refuse.
+ */
+export function bindHostFromArgv(argv = process.argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--bind-host')
+            return argv[i + 1];
+        if (arg.startsWith('--bind-host='))
+            return arg.slice('--bind-host='.length);
+    }
+    return undefined;
+}
+export async function collectDiscoveryFacts(ctx, env = process.env) {
+    const root = ctx.project.root;
+    const [checks, repo, config, workspace] = await Promise.all([
+        detectEnvironment(),
+        getRepoInfo(root),
+        loadConfig(root),
+        loadWorkspaceConfig(),
+    ]);
+    const forge = resolveForge(repo);
+    // Awaited, unlike `/health`: a tool call can afford the one `gh` probe, and a settled answer
+    // beats "not checked yet". The driver caches it for 60 s either way.
+    const availability = forge ? await forge.detect().catch(() => ({ available: false })) : null;
+    providerAuth ??= new ProviderAuthService();
+    const providers = applyProviderEnablement(await providerAuth.status(), workspace.disabledProviders);
+    const own = workspace.projects.find((p) => p.id === ctx.project.id);
+    const resources = workspace.resources;
+    const projectMaxParallel = own?.maxParallel ?? null;
+    const projectMemoryLimitMb = typeof config.memoryLimitMb === 'number' && config.memoryLimitMb > 0 ? config.memoryLimitMb : null;
+    return {
+        project: ctx.project,
+        xezarVersion: ctx.xezarVersion,
+        health: {
+            repo,
+            checks,
+            defaultRunner: config.defaultRunner,
+            forge: forge ? { kind: forge.kind, ...availability } : null,
+            capabilities: resolveCapabilities(env, bindHostFromArgv(), workspace.followups),
+        },
+        config: { baseBranch: config.baseBranch ?? null, modelsLocked: agentModelsLocked(root, env) },
+        providers,
+        limits: {
+            maxParallel: {
+                effective: projectMaxParallel ?? resources.maxParallel,
+                project: projectMaxParallel,
+                workspace: resources.maxParallel,
+            },
+            memoryLimitMb: {
+                effective: projectMemoryLimitMb ?? resources.memoryLimitMb,
+                project: projectMemoryLimitMb,
+                workspace: resources.memoryLimitMb,
+            },
+            maxMonitoringSessions: resources.maxMonitoringSessions,
+            monitoringWakeIntervalMinutes: resources.monitoringWakeIntervalMinutes,
+            autoResumeOnUsageLimit: resources.autoResumeOnUsageLimit,
+            idleTimeoutMinutes: resources.idleTimeoutMinutes,
+            worktreeRetention: config.worktreeRetention,
+        },
+    };
+}
+/** The authoritative text block (D-05): a one-line orientation, then the whole result. */
+export function discoveryText(discovery) {
+    const closed = discovery.actions.filter((a) => a.status !== 'available');
+    const lines = [
+        `Bound to xezar project "${discovery.project.name}" (id ${discovery.project.id}).`,
+        ...closed.map((a) => `${a.status === 'read-only' ? 'Read-only' : 'Unavailable'}: ${a.label} — ${a.reason}`),
+        '',
+        JSON.stringify(discovery, null, 2),
+    ];
+    return lines.join('\n');
+}
+export const discoverProjectTool = defineTool({
+    name: 'discover_project',
+    title: 'Discover the bound project',
+    description: 'Read which xezar project this session is bound to, its effective capabilities and limits, and which actions are available. Every action that is unavailable or read-only says why. Call it at the start of a session and again after a person changes settings. It takes no arguments: the project comes from the connection, never from a parameter.',
+    inputSchema: z.strictObject({}),
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async call(_args, ctx) {
+        const discovery = buildDiscovery(await collectDiscoveryFacts(ctx));
+        return textResult(discoveryText(discovery), discovery);
+    },
+});
+//# sourceMappingURL=discovery.js.map

package/dist/mcp/tools/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/mcp/tools/discovery.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/execution-control.d.ts

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+import { type GetRunValue, type ServiceDispatch } from '../service-adapter.ts';
+import { type McpToolContext } from '../tool.ts';
+/**
+ * Execution control and session messaging for the bound project's own tasks (#94, F-08, F-09,
+ * M-03, M-04; inventory I-032, I-034–I-040).
+ *
+ * WHAT IT CAN TARGET. A task of the project this connection is bound to, named by its run id —
+ * and nothing else. Every action first reads the task through the shared service adapter (#89),
+ * whose scope is the connection's project, so another project's task is a 404 before anything
+ * is dispatched. There is no argument for a process id, a signal, a command or a path, and this
+ * module starts or signals no process itself: every effect is one of the cockpit's own routes,
+ * and the RunManager behind that route is the only thing that ever touches an agent process.
+ * F-08 is explicit that a generic "kill PID" does not meet the boundary; none exists here.
+ *
+ * THE SAME STATE MACHINE AS THE COCKPIT. Each action is offered in exactly the states the
+ * cockpit offers it (`run-actions.ts` `runActionFlags`, `task-thread.tsx`'s composer routing,
+ * `ask-answer.ts` `askDeliveryMode`), and refused — with nothing changed — in every other one.
+ * The refusal is checked here AND again by the route, so a state that moved between the read and
+ * the write is still refused by the service.
+ *
+ * NO NEW STATES. Every action lands the task in a state the cockpit already reaches, through the
+ * cockpit's own route, so every exit a state already has — a user message, the autonomous
+ * nudge, the monitoring wake timer, cancel, finish, the idle close — still applies to it.
+ * Nothing here parks a task, holds a session open or schedules anything.
+ *
+ * WHERE THE SERVICE COMES FROM. `McpToolContext` does not carry the service's in-process entry
+ * yet (#86 shipped it without one, #89 left widening it to later work). This tool reads it from
+ * an optional `service` field on the context and answers an honest tool error when it is absent;
+ * the service passing its app there is the one wiring step this tool cannot take from its own
+ * file.
+ *
+ * STALE WRITES (#250, N-03). Every action changes the task, so every action requires the
+ * `expectedVersion` a `task_read` of it handed out, and sends it to the route, which compares it
+ * with the task's current version in the same synchronous stretch as the engine call. A task that
+ * moved since is refused with nothing applied (`status: "conflict"`, `error: "stale_version"`,
+ * `currentVersion`). The version moves with every event a task records, so a RUNNING task's
+ * version moves while its agent works: read it right before acting on a running task. The same holds
+ * for an answer that meets an idle close: the close changes the task, so the resume after it is
+ * refused as stale rather than retried with a fresh version — the leader reads again and answers
+ * again (D-06 § 4.4 rule 3).
+ */
+export declare const EXECUTION_CONTROL_ACTIONS: readonly ['cancel', 'finish', 'continue', 'send_message', 'answer_question', 'edit_queued_message', 'remove_queued_message', 'cancel_auto_resume'];
+export type ExecutionControlAction = (typeof EXECUTION_CONTROL_ACTIONS)[number];
+/** The cockpit's own schedule (`ask-answer.ts`): the idle timer closes the backend before the
+ *  RunManager has released the run, so a resume can arrive a few milliseconds early. Only that
+ *  exact refusal is retried; every other 409 is an answer. */
+export declare const IDLE_TEARDOWN_RETRY_DELAYS_MS: readonly [50, 100, 200, 400, 800, 1000, 1000, 1000, 1000];
+/** The context this tool reads beyond `McpToolContext`: the running service's in-process entry. */
+export type ExecutionControlContext = McpToolContext & {
+    readonly service?: ServiceDispatch;
+};
+export declare const executionControlInputSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        answer_question: "answer_question";
+        cancel: "cancel";
+        cancel_auto_resume: "cancel_auto_resume";
+        continue: "continue";
+        edit_queued_message: "edit_queued_message";
+        finish: "finish";
+        remove_queued_message: "remove_queued_message";
+        send_message: "send_message";
+    }>;
+    runId: z.ZodString;
+    expectedVersion: z.ZodString;
+    operationId: z.ZodString;
+    text: z.ZodOptional<z.ZodString>;
+    images: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mediaType: z.ZodString;
+        data: z.ZodString;
+    }, z.core.$strip>>>;
+    finishAs: z.ZodOptional<z.ZodEnum<{
+        accept_review: "accept_review";
+        close_session: "close_session";
+    }>>;
+    questionId: z.ZodOptional<z.ZodString>;
+    answers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        choices: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    messageId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ExecutionControlInput = z.output<typeof executionControlInputSchema>;
+/** The result, text block and `structuredContent` alike (D-05 § 6.8: the text is authoritative,
+ *  and the result is a slim projection rather than the task record). */
+export declare const executionControlResultSchema: z.ZodObject<{
+    applied: z.ZodOptional<z.ZodLiteral<false>>;
+    error: z.ZodOptional<z.ZodLiteral<"stale_version">>;
+    resource: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    currentVersion: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    changedSince: z.ZodOptional<z.ZodLiteral<true>>;
+    guidance: z.ZodOptional<z.ZodLiteral<"Not applied: this changed after you read it. Read the current state and decide again; a new decision is a new operation.">>;
+    action: z.ZodEnum<{
+        answer_question: "answer_question";
+        cancel: "cancel";
+        cancel_auto_resume: "cancel_auto_resume";
+        continue: "continue";
+        edit_queued_message: "edit_queued_message";
+        finish: "finish";
+        remove_queued_message: "remove_queued_message";
+        send_message: "send_message";
+    }>;
+    accepted: z.ZodBoolean;
+    status: z.ZodEnum<{
+        accepted: "accepted";
+        cancelled: "cancelled";
+        conflict: "conflict";
+        done: "done";
+        failed: "failed";
+    }>;
+    subject: z.ZodObject<{
+        type: z.ZodLiteral<"run">;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    runStatus: z.ZodOptional<z.ZodString>;
+    delivery: z.ZodOptional<z.ZodEnum<{
+        amended: "amended";
+        continued: "continued";
+        deferred: "deferred";
+        live: "live";
+        resumed: "resumed";
+    }>>;
+    questionId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    hadPendingAutoResume: z.ZodOptional<z.ZodBoolean>;
+    reason: z.ZodOptional<z.ZodString>;
+    origin: z.ZodLiteral<"mcp">;
+}, z.core.$strip>;
+export type ExecutionControlResult = z.infer<typeof executionControlResultSchema>;
+type Run = GetRunValue;
+/** `ask-answer.ts` `askDeliveryMode`. */
+export declare function askDeliveryMode(run: Pick<Run, 'status' | 'steps'>): 'live' | 'resume' | 'unavailable';
+declare const askQuestionSchema: z.ZodObject<{
+    header: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+    }, z.core.$loose>>;
+    multiSelect: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+type AskQuestion = z.infer<typeof askQuestionSchema>;
+export interface PendingQuestion {
+    requestId: string;
+    questions: AskQuestion[];
+}
+/**
+ * The one question an answer can reach: the newest `ask.requested` with no `user-message` after
+ * it — the cockpit's reducer (`thread-state.ts`), which resolves whichever ask is pending with
+ * the next user message. An older ask that a newer one superseded is NOT pending, however
+ * unanswered it looks: a message sent for it would be read as the answer to the newer one.
+ * `events` may be in any order; a malformed ask is skipped, exactly as the reducer skips it.
+ */
+export declare function pendingQuestionIn(events: ReadonlyArray<{
+    seq: number;
+    type: string;
+} & Record<string, unknown>>): PendingQuestion | null | undefined;
+/** The ask card's answer text (`ask-card.tsx` `formatAnswer`), one line per question. */
+export declare function formatAnswers(questions: readonly AskQuestion[], answers: ReadonlyArray<{
+    choices: readonly string[];
+}>): {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Build the tool over an injectable wait, so the idle-teardown schedule is testable. */
+export declare function createExecutionControlTool(wait?: (ms: number) => Promise<void>): import("../tool.ts").McpTool<z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>;
+export declare const executionControlTool: import("../tool.ts").McpTool<z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>;
+export {};