dsh-plugin-coding-delegate 0.0.0-stage → 0.2.2

package/cordis.patch.example.yml

@@ -0,0 +1,48 @@
+# EXAMPLE ONLY - NOT APPLIED AUTOMATICALLY.
+#
+# These entries DO modify provider configuration, which is exactly why they are not shipped
+# as an automatic patch. Copy what you need into your DSH profile
+# (profiles/<name>/cordis.patch.yml) or into ~/.dsh/settings.yaml.
+#
+# This is Option 1 from README.md, "Configuring providers": a local LM Studio worker plus
+# DeepSeek Cloud. For any other OpenAI-compatible endpoint (vLLM, Ollama, llama.cpp, a
+# remote gateway, ...) change baseURL and the model id, then point the plugin's
+# localProvider / localModel at it.
+
+# The plugin itself. Delete this whole block to accept the built-in defaults listed in
+# cordis.patch.yml.
+- id: local-router
+  config:
+    localProvider: 'lm-studio'
+    localModel: 'qwen/qwen3.8-27b'
+    cloudProvider: 'deepseek-official'
+    cloudModel: 'deepseek-chat'
+    # guardAskPaths REPLACES the built-in default rather than extending it, so list every
+    # path that should stay approval-eligible instead of hard-denied.
+    guardAskPaths:
+      - 'tests/'
+      - 'tools/'
+    # A tripped DLP firewall reroutes to the local worker rather than refusing the request.
+    dlpAction: 'local'
+    # Uncomment to run a lead agent on the local endpoint. The provider list is derived from the LEAD
+    # profile, so the id is declared in one place. Do NOT point this at cloudProvider -- the hook would
+    # stop pinning the architect, and source could leave the machine.
+    # leadTier: true
+
+- id: llm-pi-ai
+  name: '@deepseek-ai/dsh-llm-pi-ai'
+  config:
+    providers:
+      lm-studio:
+        api: openai-completions
+        baseURL: http://127.0.0.1:1234/v1
+        apiKeyEnv: LM_STUDIO_API_KEY
+        models:
+          - id: qwen/qwen3.8-27b
+            name: 'Qwen 3.8 27B Local'
+            maxTokens: 16384
+
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# Applied by DSH when this plugin is bundled into a profile.
+#
+# THIS PATCH REGISTERS THE PLUGIN ONLY. It adds, removes and modifies no LLM provider,
+# no model and no API key -- provider configuration is yours to own.
+#
+# With no config block the plugin uses its built-in defaults (localProvider lm-studio,
+# localModel qwen/qwen3.8-27b, cloudProvider deepseek-official, cloudModel deepseek-chat).
+# Override them in your own profile patch; cordis.patch.example.yml has a complete
+# worked example, and README.md "Configuring providers" covers other endpoints and
+# cloud-only setups.
+- insert:
+    - id: local-router
+      name: 'dsh-plugin-coding-delegate'

package/dist/attestation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The scope decision for one attestation: a human claim may only cover files this unit wrote.
+ *
+ * `OPERATOR_ATTESTED` says a person reviewed content. Before this existed, the gate was the unit's
+ * status alone, and an ANSWER-ONLY delegation reaches SUCCESS without writing anything -- so a caller
+ * could name any readable path in the workspace and have it recorded as human-reviewed. The status was
+ * true and the claim was unrelated to it.
+ *
+ * A unit that wrote files cannot reach SUCCESS unverified (resolveDelegateStatus returns UNVERIFIED),
+ * so requiring membership in `filesWritten` also requires that verification ran and passed.
+ *
+ * Matches on canonicalised paths, the same comparison `evaluateUnitScope` uses, so redundant segments
+ * and a symlinked spelling of one file are a single target rather than two. Note that
+ * `canonicalisePath` resolves a RELATIVE input against process.cwd(), while `filesWritten` holds
+ * absolute paths, so a relative attestTarget is refused when cwd differs from the workspace. That
+ * fails closed and is deliberate.
+ */
+export declare function selectAttestableTargets(input: {
+    requested: Array<string | undefined | null>;
+    filesWritten: Array<string | undefined | null>;
+    operator: string;
+}): {
+    attestable: string[];
+    refused: string[];
+};

package/dist/attestation.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectAttestableTargets = selectAttestableTargets;
+const paths_1 = require("./paths");
+/**
+ * The scope decision for one attestation: a human claim may only cover files this unit wrote.
+ *
+ * `OPERATOR_ATTESTED` says a person reviewed content. Before this existed, the gate was the unit's
+ * status alone, and an ANSWER-ONLY delegation reaches SUCCESS without writing anything -- so a caller
+ * could name any readable path in the workspace and have it recorded as human-reviewed. The status was
+ * true and the claim was unrelated to it.
+ *
+ * A unit that wrote files cannot reach SUCCESS unverified (resolveDelegateStatus returns UNVERIFIED),
+ * so requiring membership in `filesWritten` also requires that verification ran and passed.
+ *
+ * Matches on canonicalised paths, the same comparison `evaluateUnitScope` uses, so redundant segments
+ * and a symlinked spelling of one file are a single target rather than two. Note that
+ * `canonicalisePath` resolves a RELATIVE input against process.cwd(), while `filesWritten` holds
+ * absolute paths, so a relative attestTarget is refused when cwd differs from the workspace. That
+ * fails closed and is deliberate.
+ */
+function selectAttestableTargets(input) {
+    // No operator identity is a refusal, not a value to invent -- unchanged from the existing contract.
+    if (!input.operator || !input.operator.trim()) {
+        return { attestable: [], refused: input.requested.filter(Boolean).map(String) };
+    }
+    const written = [];
+    for (const f of input.filesWritten) {
+        if (typeof f === 'string' && f.trim())
+            written.push((0, paths_1.canonicalisePath)(f));
+    }
+    const attestable = [];
+    const refused = [];
+    for (const raw of input.requested) {
+        if (typeof raw !== 'string' || !raw.trim())
+            continue;
+        const canonical = (0, paths_1.canonicalisePath)(raw);
+        if (written.includes(canonical))
+            attestable.push(raw);
+        else
+            refused.push(raw);
+    }
+    return { attestable, refused };
+}

package/dist/containment.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The destination decision for one delegation: which directory a worker may write into.
+ *
+ * `workspaceDir` is a model-visible tool argument, and it REPLACED the session root as the trusted
+ * base for every emission check. Containment itself was never broken -- `evaluateEmissionPath`
+ * canonicalises both sides, so a symlink or a `..` cannot escape whatever base it is given. What was
+ * wrong is that the base was chosen by the caller being contained. A prompt-injected architect could
+ * name any directory on the host and write there with no refusal, which turned "the worker cannot
+ * escape its workspace" into "the worker cannot escape whatever directory it named".
+ *
+ * Four rows, and the third is what keeps external delegation possible:
+ *
+ *   omitted                              -> trusted, the session root
+ *   within the session root              -> trusted
+ *   outside, but under an allowlist root -> trusted, the operator's explicit grant
+ *   outside and not allowlisted          -> operator prompt; refused when no approval is reachable
+ *
+ * Auto-resolved roots are NOT exempt. `resolveWorkspaceDir` reads environment variables and ctx
+ * services, and a compromise there must not silently widen containment. Omission is trusted because
+ * the caller said nothing, not because the resolved value is known good.
+ */
+export declare function resolveWorkspaceContainment(input: {
+    requested?: string | null;
+    sessionRoot: string;
+    allowedRoots?: Array<string | undefined | null>;
+    canPrompt: boolean;
+}): {
+    trusted: boolean;
+    dir?: string;
+    needsApproval: boolean;
+    reason?: string;
+    source: string;
+};

package/dist/containment.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWorkspaceContainment = resolveWorkspaceContainment;
+const paths_1 = require("./paths");
+/**
+ * The destination decision for one delegation: which directory a worker may write into.
+ *
+ * `workspaceDir` is a model-visible tool argument, and it REPLACED the session root as the trusted
+ * base for every emission check. Containment itself was never broken -- `evaluateEmissionPath`
+ * canonicalises both sides, so a symlink or a `..` cannot escape whatever base it is given. What was
+ * wrong is that the base was chosen by the caller being contained. A prompt-injected architect could
+ * name any directory on the host and write there with no refusal, which turned "the worker cannot
+ * escape its workspace" into "the worker cannot escape whatever directory it named".
+ *
+ * Four rows, and the third is what keeps external delegation possible:
+ *
+ *   omitted                              -> trusted, the session root
+ *   within the session root              -> trusted
+ *   outside, but under an allowlist root -> trusted, the operator's explicit grant
+ *   outside and not allowlisted          -> operator prompt; refused when no approval is reachable
+ *
+ * Auto-resolved roots are NOT exempt. `resolveWorkspaceDir` reads environment variables and ctx
+ * services, and a compromise there must not silently widen containment. Omission is trusted because
+ * the caller said nothing, not because the resolved value is known good.
+ */
+function resolveWorkspaceContainment(input) {
+    const norm = (p) => (0, paths_1.canonicalisePath)(String(p));
+    const session = norm(input.sessionRoot);
+    const requested = typeof input.requested === 'string' ? input.requested.trim() : '';
+    if (!requested) {
+        return { trusted: true, dir: session, needsApproval: false, source: 'session-root' };
+    }
+    const dest = norm(requested);
+    // Segment-wise containment, not string prefixing: `isPathWithin` compares path parts, so a sibling
+    // directory whose NAME merely begins with the root's name is not treated as inside it.
+    if ((0, paths_1.isPathWithin)(session, dest)) {
+        return { trusted: true, dir: dest, needsApproval: false, source: 'within-session-root' };
+    }
+    const granted = (input.allowedRoots || [])
+        .filter((r) => typeof r === 'string' && r.trim().length > 0)
+        .map(norm);
+    if (granted.some((root) => (0, paths_1.isPathWithin)(root, dest))) {
+        return { trusted: true, dir: dest, needsApproval: false, source: 'emitAllowlist' };
+    }
+    const reason = `Delegation requested workspaceDir '${requested}', which resolves to '${dest}' -- outside the ` +
+        `session workspace '${session}' and outside every configured emitAllowlist root. Writing there ` +
+        `is not authorised by configuration.`;
+    if (input.canPrompt) {
+        return {
+            trusted: false,
+            dir: dest,
+            needsApproval: true,
+            reason,
+            source: 'outside-awaiting-approval',
+        };
+    }
+    return {
+        trusted: false,
+        needsApproval: false,
+        reason: reason + ' No approval service is reachable, so the delegation is refused.',
+        source: 'outside-refused',
+    };
+}

package/dist/context-quality.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Context-quality counters: the measurement that turns this plugin's central claim into an observation.
+ *
+ * README is explicit that the claim is currently argued rather than shown -- "What the plugin does not
+ * yet do is measure context quality; it measures tokens." This module is the missing half.
+ *
+ * It folds DSH's OWN session events, read from the installed packages rather than invented here:
+ *
+ *   dsh-session    augments `SessionEventMap` with `turn/start`, `turn/end`, `step/start`, `step/end`, ...
+ *   dsh-compaction augments it with `compaction/start`, `compaction/summary`, `compaction/end`,
+ *                  `compaction/prune`
+ *
+ * `compaction/summary` and `compaction/prune` each carry `shadowedTokenCount`: the host's own figure for
+ * how much context the replacement removed, and the exact span it replaced. That is why this module
+ * counts rather than estimates. The number that matters is reported by the harness, not guessed by the
+ * plugin, which is the difference between evidence and a proxy.
+ *
+ * Two properties the fold must keep, because it runs inside a firehose handler:
+ *
+ * 1. **It never throws.** It is attached to every session event; an exception there would put this
+ *    plugin's error into someone else's event loop. Unusable input is ignored, never fatal.
+ * 2. **An uninteresting event returns the same reference.** DSH's own projections do this so the change
+ *    feed stays quiet, and the same discipline here keeps a long session from allocating on every tool
+ *    result it will never look at.
+ *
+ * A note on what these counters do NOT see: the `session/event` firehose does not publish events that
+ * entered through construction (replay, fork, resume), so a resumed session is counted from the resume
+ * rather than from its true beginning. That is a real limit of the measurement and is recorded in
+ * `docs/findings.md` rather than glossed.
+ */
+export interface ContextQuality {
+    /** Turns opened in this process. */
+    turns: number;
+    /** Steps opened in this process. */
+    steps: number;
+    /** Compactions that produced a summary -- the model-assisted kind. */
+    compactions: number;
+    /** Model-free prunes. Counted separately because they cost no model call. */
+    prunes: number;
+    /**
+     * Compactions that ended with an error. Worth counting separately: a failed compaction leaves the
+     * window exactly as bloated as it was, so it is the opposite of the thing this measures.
+     */
+    failedCompactions: number;
+    /** Tokens the host reported as shadowed -- reclaimed -- by summaries and prunes. */
+    tokensReclaimed: number;
+    /**
+     * The prompt the model actually received on the most recent model call: the window as it stood at
+     * that step. Measured against a real session rather than inferred from a field name.
+     *
+     * Explicitly NOT `usage.inputTokens`, which is what the first version of this counter used and why
+     * it was wrong. That field is only the UNCACHED portion of the prompt: a live call reported
+     * `inputTokens` 228 alongside `cacheReadTokens` 659456 and `totalTokens` 661541, with
+     * `input + cacheRead + output === total` exactly. Reading it as the window understates a 660k-token
+     * window by a factor of about 2900 — in the direction that makes a full window look empty.
+     */
+    lastPromptTokens: number;
+    /**
+     * The high-water mark of that figure. This, not the last value, is the number that forces a
+     * compaction, and it is the one to compare against a window.
+     */
+    peakPromptTokens: number;
+    /** The context window the route advertised, when it advertised one. */
+    contextWindow: number | null;
+    /**
+     * The route the session's model calls are going to, as `provider/model`.
+     *
+     * Recorded because the counters above cannot say whether they are the *frontier* figures without it.
+     * With the default two-tier configuration every session call is the architect's, so they are; with a
+     * lead tier configured the session is pinned elsewhere and they are that model's instead. Labelling
+     * them "frontier" without the route would be the kind of claim this project tries not to make.
+     */
+    route: string;
+}
+export declare const EMPTY_CONTEXT_QUALITY: ContextQuality;
+/** Fold one session event into the counters. Pure; returns `state` unchanged when it does not care. */
+export declare function foldContextQuality(state: ContextQuality, event: unknown): ContextQuality;
+/** One line, for a `CONTEXT_QUALITY` trace entry. Never multi-line: it is a trace payload. */
+export declare function describeContextQuality(state: ContextQuality): string;

package/dist/context-quality.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Context-quality counters: the measurement that turns this plugin's central claim into an observation.
+ *
+ * README is explicit that the claim is currently argued rather than shown -- "What the plugin does not
+ * yet do is measure context quality; it measures tokens." This module is the missing half.
+ *
+ * It folds DSH's OWN session events, read from the installed packages rather than invented here:
+ *
+ *   dsh-session    augments `SessionEventMap` with `turn/start`, `turn/end`, `step/start`, `step/end`, ...
+ *   dsh-compaction augments it with `compaction/start`, `compaction/summary`, `compaction/end`,
+ *                  `compaction/prune`
+ *
+ * `compaction/summary` and `compaction/prune` each carry `shadowedTokenCount`: the host's own figure for
+ * how much context the replacement removed, and the exact span it replaced. That is why this module
+ * counts rather than estimates. The number that matters is reported by the harness, not guessed by the
+ * plugin, which is the difference between evidence and a proxy.
+ *
+ * Two properties the fold must keep, because it runs inside a firehose handler:
+ *
+ * 1. **It never throws.** It is attached to every session event; an exception there would put this
+ *    plugin's error into someone else's event loop. Unusable input is ignored, never fatal.
+ * 2. **An uninteresting event returns the same reference.** DSH's own projections do this so the change
+ *    feed stays quiet, and the same discipline here keeps a long session from allocating on every tool
+ *    result it will never look at.
+ *
+ * A note on what these counters do NOT see: the `session/event` firehose does not publish events that
+ * entered through construction (replay, fork, resume), so a resumed session is counted from the resume
+ * rather than from its true beginning. That is a real limit of the measurement and is recorded in
+ * `docs/findings.md` rather than glossed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_CONTEXT_QUALITY = void 0;
+exports.foldContextQuality = foldContextQuality;
+exports.describeContextQuality = describeContextQuality;
+exports.EMPTY_CONTEXT_QUALITY = {
+    turns: 0,
+    steps: 0,
+    compactions: 0,
+    prunes: 0,
+    failedCompactions: 0,
+    tokensReclaimed: 0,
+    lastPromptTokens: 0,
+    peakPromptTokens: 0,
+    contextWindow: null,
+    route: '',
+};
+/**
+ * The token figure the host reported for a replaced span, or null when it is missing or unusable.
+ *
+ * Both fields this reads are REQUIRED by DSH's own types, so a well-formed event always carries one. A
+ * missing or non-numeric value therefore means the event is not what it claims to be, and the caller
+ * refuses to count it -- a completion is only counted with its receipt, so the compaction count and the
+ * reclaimed-token count can never disagree about whether something happened.
+ */
+function shadowedTokens(data) {
+    const value = data?.shadowedTokenCount;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+        return null;
+    return value;
+}
+/**
+ * The prompt one model call received, or null when the record is unusable.
+ *
+ * `inputTokens` alone is NOT that number, and reading it as though it were is the defect this function
+ * was rewritten to fix: measured on a live session, a call reported `inputTokens` 228 with
+ * `cacheReadTokens` 659456 and `totalTokens` 661541, and `input + cacheRead + output === total` exactly.
+ * So `inputTokens` counts only the uncached remainder, and the cached prefix — which on any caching
+ * provider is most of the window — has to be added back.
+ *
+ * Null is load-bearing rather than cosmetic: a call that reported nothing must leave the last known
+ * figure standing. Treating it as zero would render a full window as an empty one, which is the wrong
+ * direction for a measurement whose whole purpose is to show the window filling up.
+ */
+function promptTokens(usage) {
+    const fresh = usage?.inputTokens;
+    if (typeof fresh !== 'number' || !Number.isFinite(fresh) || fresh < 0)
+        return null;
+    const cached = usage?.cacheReadTokens;
+    const cacheRead = typeof cached === 'number' && Number.isFinite(cached) && cached >= 0 ? cached : 0;
+    return fresh + cacheRead;
+}
+/** The advertised context window, or null when absent or not a positive finite number. */
+function advertisedWindow(data) {
+    const value = data?.contextWindow;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+        return null;
+    return value;
+}
+/** Fold one session event into the counters. Pure; returns `state` unchanged when it does not care. */
+function foldContextQuality(state, event) {
+    // The event arrives from a firehose typed `any`, so this cast is a claim rather than a guarantee, and
+    // the guards inside the readers below are what keep it safe at runtime. Its value is at COMPILE time:
+    // the cases and their payloads now come from the host's own `SessionEventMap`, so a renamed event or a
+    // moved field fails the build instead of quietly zeroing a counter.
+    if (!event || typeof event !== 'object')
+        return state;
+    const candidate = event;
+    switch (candidate.type) {
+        case 'turn/start':
+            return { ...state, turns: state.turns + 1 };
+        case 'step/start':
+            return { ...state, steps: state.steps + 1 };
+        case 'compaction/summary': {
+            const tokens = shadowedTokens(candidate.data);
+            if (tokens === null)
+                return state;
+            return {
+                ...state,
+                compactions: state.compactions + 1,
+                tokensReclaimed: state.tokensReclaimed + tokens,
+            };
+        }
+        case 'compaction/prune': {
+            const tokens = shadowedTokens(candidate.data);
+            if (tokens === null)
+                return state;
+            return {
+                ...state,
+                prunes: state.prunes + 1,
+                tokensReclaimed: state.tokensReclaimed + tokens,
+            };
+        }
+        case 'compaction/end': {
+            // `error` is present only on an unsuccessful attempt, which is the one worth counting here.
+            if (typeof candidate.data?.error !== 'string' || !candidate.data.error)
+                return state;
+            return { ...state, failedCompactions: state.failedCompactions + 1 };
+        }
+        case 'assistant/message': {
+            const tokens = promptTokens(candidate.data?.usage);
+            // No reported usage means no new information. Returning `state` keeps the last known window size
+            // standing rather than reporting the call as free.
+            if (tokens === null)
+                return state;
+            return {
+                ...state,
+                lastPromptTokens: tokens,
+                peakPromptTokens: Math.max(state.peakPromptTokens, tokens),
+            };
+        }
+        case 'request/context': {
+            const window = advertisedWindow(candidate.data);
+            const provider = typeof candidate.data?.provider === 'string' ? candidate.data.provider : '';
+            const model = typeof candidate.data?.model === 'string' ? candidate.data.model : '';
+            const route = provider && model ? provider + '/' + model : state.route;
+            // Both figures are optional on this event, and it is only logged when the route or capacity
+            // changes, so a repeat with nothing new must not allocate.
+            if (window === null && route === state.route)
+                return state;
+            return { ...state, contextWindow: window ?? state.contextWindow, route };
+        }
+        default:
+            return state;
+    }
+}
+/** One line, for a `CONTEXT_QUALITY` trace entry. Never multi-line: it is a trace payload. */
+function describeContextQuality(state) {
+    return (state.turns +
+        ' turn(s), ' +
+        state.steps +
+        ' step(s), ' +
+        state.compactions +
+        ' compaction(s), ' +
+        state.prunes +
+        ' prune(s), ' +
+        state.failedCompactions +
+        ' failed compaction(s), ' +
+        state.tokensReclaimed +
+        ' token(s) reclaimed, ' +
+        (state.contextWindow === null
+            ? state.lastPromptTokens + ' token(s) at the last call'
+            : state.lastPromptTokens +
+                '/' +
+                state.contextWindow +
+                ' token(s) at the last call') +
+        (state.peakPromptTokens > state.lastPromptTokens
+            ? ' (peak ' + state.peakPromptTokens + ')'
+            : '') +
+        (state.route ? ' on ' + state.route : ''));
+}

package/dist/context.d.ts

@@ -0,0 +1,39 @@
+/** One file the architect wants the worker to see. Names and ranges only, never contents. */
+export interface ContextRequest {
+    path: string;
+    startLine?: number;
+    endLine?: number;
+}
+/**
+ * What the architect is told about an injection. Deliberately has no `content` field — the whole
+ * point is that the code travels to the worker and does not travel back.
+ */
+export interface ContextInjection {
+    path: string;
+    relativeName: string;
+    lineRange: {
+        start: number;
+        end: number;
+    } | null;
+    lines: number;
+    bytes: number;
+    sha256: string;
+}
+export interface ContextResolution {
+    injected: ContextInjection[];
+    text: string;
+    errors: string[];
+}
+/**
+ * Injected context competes with the instruction for the worker's input window, so the budget is a
+ * safety bound rather than a caller preference. Over budget refuses; it never truncates quietly,
+ * because a worker given half a file answers confidently about a file it only half saw.
+ */
+export declare const DEFAULT_CONTEXT_MAX_BYTES = 32768;
+/**
+ * Read the files the architect named and render them for the worker's prompt. Containment matches
+ * emission exactly: the same resolution, and the same refusal of escapes and absolute paths outside
+ * the root, because reading a file in order to transmit it is an egress route and deserves the same
+ * scepticism as writing one.
+ */
+export declare function resolveContextFiles(requests: ContextRequest[] | undefined, baseDir: string, allowedRoots?: string[], maxBytes?: number): ContextResolution;

package/dist/context.js

@@ -0,0 +1,136 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONTEXT_MAX_BYTES = void 0;
+exports.resolveContextFiles = resolveContextFiles;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const emission_1 = require("./emission");
+/**
+ * Injected context competes with the instruction for the worker's input window, so the budget is a
+ * safety bound rather than a caller preference. Over budget refuses; it never truncates quietly,
+ * because a worker given half a file answers confidently about a file it only half saw.
+ */
+exports.DEFAULT_CONTEXT_MAX_BYTES = 32768;
+/**
+ * Read the files the architect named and render them for the worker's prompt. Containment matches
+ * emission exactly: the same resolution, and the same refusal of escapes and absolute paths outside
+ * the root, because reading a file in order to transmit it is an egress route and deserves the same
+ * scepticism as writing one.
+ */
+function resolveContextFiles(requests, baseDir, allowedRoots = [], maxBytes = exports.DEFAULT_CONTEXT_MAX_BYTES) {
+    const injected = [];
+    const errors = [];
+    const sections = [];
+    let totalBytes = 0;
+    for (const request of requests ?? []) {
+        const declared = String(request?.path || '').trim();
+        if (!declared) {
+            errors.push('a contextFiles entry had no path');
+            continue;
+        }
+        const resolvedPath = path.isAbsolute(declared) ? declared : path.resolve(baseDir, declared);
+        const containment = (0, emission_1.evaluateEmissionPath)(resolvedPath, baseDir, allowedRoots);
+        if (!containment.allowed) {
+            errors.push(`context file '${declared}' was refused: ${containment.reason}`);
+            continue;
+        }
+        const declaresRange = request.startLine !== undefined || request.endLine !== undefined;
+        if (!declaresRange) {
+            try {
+                const fileSize = fs.statSync(resolvedPath).size;
+                if (fileSize > maxBytes - totalBytes) {
+                    errors.push(`context injection would exceed its ${maxBytes}-byte budget (${totalBytes + fileSize} bytes declared). ` +
+                        `Narrow the line ranges or declare fewer files.`);
+                    continue;
+                }
+            }
+            catch {
+                // stat failed; fall through to the read attempt so the existing error path reports it
+            }
+        }
+        let raw;
+        try {
+            raw = fs.readFileSync(resolvedPath, 'utf8');
+        }
+        catch (err) {
+            errors.push(`context file '${declared}' could not be read: ${err?.message || String(err)}`);
+            continue;
+        }
+        const allLines = raw.split('\n');
+        let lineRange = null;
+        let body = raw;
+        if (request.startLine !== undefined || request.endLine !== undefined) {
+            const start = Number(request.startLine ?? 1);
+            const end = Number(request.endLine ?? allLines.length);
+            if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start) {
+                errors.push(`context file '${declared}' had an invalid line range (${request.startLine}-${request.endLine})`);
+                continue;
+            }
+            if (start > allLines.length) {
+                errors.push(`context file '${declared}' has ${allLines.length} line(s), so a range starting at ${start} does not exist`);
+                continue;
+            }
+            // An over-long end is clamped rather than refused, and the clamp is reported in the record.
+            const clampedEnd = Math.min(end, allLines.length);
+            lineRange = { start, end: clampedEnd };
+            body = allLines.slice(start - 1, clampedEnd).join('\n');
+        }
+        const bytes = Buffer.byteLength(body, 'utf8');
+        if (totalBytes + bytes > maxBytes) {
+            errors.push(`context injection would exceed its ${maxBytes}-byte budget (${totalBytes + bytes} bytes declared). ` +
+                `Narrow the line ranges or declare fewer files.`);
+            continue;
+        }
+        totalBytes += bytes;
+        const relativeName = path.relative(baseDir, resolvedPath) || declared;
+        injected.push({
+            path: resolvedPath,
+            relativeName,
+            lineRange,
+            lines: body.split('\n').length,
+            bytes,
+            sha256: crypto.createHash('sha256').update(body, 'utf8').digest('hex'),
+        });
+        sections.push(`--- ${relativeName}${lineRange ? ` (lines ${lineRange.start}-${lineRange.end})` : ''} ---\n${body}`);
+    }
+    // Any error refuses the whole injection, and the caller refuses the delegation. A partial view is
+    // worse than none: the worker would be asked to edit a file it had only partly been shown.
+    if (errors.length > 0)
+        return { injected: [], text: '', errors };
+    const text = sections.length > 0 ? `Declared Context:\n${sections.join('\n\n')}` : '';
+    return { injected, text, errors };
+}