devcontour-harness 0.1.0-alpha.11 → 0.1.0-alpha.13

package/lib/integrations/connector/config.d.ts

@@ -40,6 +40,7 @@ export declare const taskMappingSchema: z.ZodObject<{
         }>>;
     }, z.core.$strict>>>;
     requiredDocuments: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    context: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type TaskMapping = z.infer<typeof taskMappingSchema>;
 export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -51,6 +52,7 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     projectId: z.ZodString;
     actor: z.ZodString;
     stateDir: z.ZodOptional<z.ZodString>;
+    contextDir: z.ZodOptional<z.ZodString>;
     repository: z.ZodObject<{
         id: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
@@ -72,6 +74,7 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
             }>>;
         }, z.core.$strict>>>;
         requiredDocuments: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        context: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     completion: z.ZodDefault<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<{
@@ -122,6 +125,7 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     projectId: z.ZodString;
     actor: z.ZodString;
     stateDir: z.ZodOptional<z.ZodString>;
+    contextDir: z.ZodOptional<z.ZodString>;
     repository: z.ZodObject<{
         id: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
@@ -143,6 +147,7 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
             }>>;
         }, z.core.$strict>>>;
         requiredDocuments: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        context: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     completion: z.ZodDefault<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<{

package/lib/integrations/connector/config.js

@@ -57,6 +57,13 @@ export const taskMappingSchema = z.strictObject({
     criteria: z.array(criterionMappingSchema).max(100).default([]),
     /** Документы, без которых запуск блокируется (ID, ключ или имя). Остальные — дополнительные. */
     requiredDocuments: z.array(z.string().min(1).max(200)).max(30).default([]),
+    /**
+     * Локальные пакеты контекста поручения — каталоги `<contextDir>/<id>` (например,
+     * оверлей controller-mode). Закрепляются в снимке вместе с контекстом задачи;
+     * изменение набора или содержимого пакетов — новый снимок и новое
+     * согласование; semantic digest задачи от них не зависит.
+     */
+    context: z.array(idSchema).min(1).max(10).optional(),
 });
 const relaySettings = z.record(z.string(), z.unknown());
 const common = {
@@ -69,6 +76,8 @@ const common = {
      * для процессов, разделяющих этот каталог.
      */
     stateDir: z.string().min(1).max(1000).optional(),
+    /** Каталог пакетов `tasks[].context` (относительно файла конфигурации); по умолчанию `work/context`. */
+    contextDir: z.string().min(1).max(1000).optional(),
     repository: z.strictObject({
         id: idSchema,
         /** Путь репозитория для сверки с политикой (относительно файла конфигурации). */
@@ -161,6 +170,12 @@ export function parseConfig(value, baseDir, file) {
     const dup = refs.find((r, i) => refs.indexOf(r) !== i);
     if (dup)
         throw new HarnessError('INVALID_INPUT', 'source: задача указана дважды: ' + dup);
+    // ID контекста задачи — `c` + 20 hex (contextIdOf): локальный пакет не может его занять.
+    const taken = parsed.data.tasks
+        .flatMap((t) => t.context ?? [])
+        .find((id) => /^c[0-9a-f]{20}$/.test(id));
+    if (taken)
+        throw new HarnessError('INVALID_INPUT', `source: пакет контекста ${taken} совпадает по форме с ID контекста задачи; выберите другое имя`);
     return { config: parsed.data, baseDir, ...(file ? { file } : {}) };
 }
 export function loadConfig(path) {
@@ -204,7 +219,9 @@ export const contextIdOf = (orderId) => 'c' + orderId.slice(1);
 export const graphIdOf = (provider, projectId, taskIds) => 'g' + short([provider, projectId, ...[...taskIds].sort()].join('\n'));
 /** Digest сопоставления задачи: входит в semantic digest — смена mapping требует нового согласования. */
 export const mappingDigest = (config, mapping) => digestOf({
-    mapping: { ...mapping, ref: undefined },
+    // Пакеты контекста — не постановка задачи: их ID и digest входят в ревизию
+    // набора (новое согласование), но доставку принятого результата не меняют.
+    mapping: { ...mapping, ref: undefined, context: undefined },
     repository: config.repository.id,
     completion: config.completion,
 });

package/lib/integrations/connector/index.d.ts

@@ -6,7 +6,7 @@
 export * from './transport.ts';
 export { connectorConfigSchema, criterionMappingSchema, taskMappingSchema, loadConfig, parseConfig, connectorIdOf, taskIdentity, parseIdentity, orderIdOf, graphIdOf, contextIdOf, mappingDigest, completionColumn, storeFileOf, type ConnectorConfig, type ConnectorConfigInput, type CriterionMapping, type TaskMapping, type LoadedConfig, } from './config.ts';
 export { ConnectorStore, LeaseLost, type OperationRecord, type OperationStatus, type StepRecord, type StepStatus, type LeaseRecord, type ReceiptRecord, type SnapshotRecord, } from './store.ts';
-export { buildSnapshot, checkIdentity, readStable, semanticDigest, takeSnapshot, assertEligible, type BuiltSnapshot, type SnapshotManifest, type SnapshotProblem, type TaskManifest, } from './snapshot.ts';
+export { buildSnapshot, checkIdentity, readStable, semanticDigest, contextLimitIssues, localContext, takeSnapshot, assertEligible, type BuiltSnapshot, type SnapshotManifest, type SnapshotProblem, type TaskManifest, } from './snapshot.ts';
 export { RelayWorkSource } from './source.ts';
 export { RelaySink, operationKey, type ReconcileDecision, type SinkOptions } from './delivery.ts';
 export { HistoryRecorder, type SessionLink } from './history.ts';

package/lib/integrations/connector/index.js

@@ -6,7 +6,7 @@
 export * from "./transport.js";
 export { connectorConfigSchema, criterionMappingSchema, taskMappingSchema, loadConfig, parseConfig, connectorIdOf, taskIdentity, parseIdentity, orderIdOf, graphIdOf, contextIdOf, mappingDigest, completionColumn, storeFileOf, } from "./config.js";
 export { ConnectorStore, LeaseLost, } from "./store.js";
-export { buildSnapshot, checkIdentity, readStable, semanticDigest, takeSnapshot, assertEligible, } from "./snapshot.js";
+export { buildSnapshot, checkIdentity, readStable, semanticDigest, contextLimitIssues, localContext, takeSnapshot, assertEligible, } from "./snapshot.js";
 export { RelayWorkSource } from "./source.js";
 export { RelaySink, operationKey } from "./delivery.js";
 export { HistoryRecorder } from "./history.js";

package/lib/integrations/connector/snapshot.d.ts

@@ -1,4 +1,4 @@
-import { HarnessError, type ContextSnapshot, type WorkGraph } from '../../contracts/index.ts';
+import { HarnessError, type ContextSnapshot, type ContextSourceEntry, type WorkGraph } from '../../contracts/index.ts';
 import { type ConnectorConfig, type TaskMapping } from './config.ts';
 import type { ReceiptRecord } from './store.ts';
 import { type CriterionRecord, type RelayTransport, type TaskRead, type TransportIdentity } from './transport.ts';
@@ -84,6 +84,15 @@ export interface SnapshotManifest {
     tasks: TaskManifest[];
     truncated: string[];
     problems: SnapshotProblem[];
+    /** Закреплённые локальные пакеты `tasks[].context`; без них поля нет. */
+    localContext?: LocalContextManifest[];
+}
+export interface LocalContextManifest {
+    id: string;
+    digest: string;
+    files: number;
+    references: number;
+    bytes: number;
 }
 export interface BuiltSnapshot {
     graph: WorkGraph;
@@ -119,12 +128,24 @@ export declare function buildSnapshot(input: {
     rounds: number;
     /** Доверенный receipt этого коннектора для задачи-зависимости вне графа. */
     receiptOf: (orderId: string) => ReceiptRecord | undefined;
+    /** Закреплённые локальные пакеты `tasks[].context` (localContext). */
+    local?: ContextSourceEntry[];
 }): BuiltSnapshot;
+/** Нарушения пределов снимка контекста: число источников, размер файла и сумма. */
+export declare function contextLimitIssues(context: ContextSnapshot): string[];
+/**
+ * Локальные пакеты `tasks[].context` из `contextDir`: те же правила, что у
+ * файлового контекста графа (каталог `<contextDir>/<id>`, `references/` —
+ * справки). Нет каталога или пакета — NOT_READY до чтения backend.
+ */
+export declare function localContext(config: ConnectorConfig, contextDir: string | undefined): Promise<ContextSourceEntry[]>;
 /** Прочитать, собрать и проверить идентичность: общий путь `source-snapshot` и `run --source`. */
 export declare function takeSnapshot(input: {
     config: ConnectorConfig;
     transport: RelayTransport;
     receiptOf: (orderId: string) => ReceiptRecord | undefined;
+    /** Абсолютный каталог пакетов `tasks[].context`. */
+    contextDir?: string;
     signal?: AbortSignal;
 }): Promise<BuiltSnapshot>;
 /** Отказ по eligibility/limits: причина и предел в сообщении, без запуска. */

package/lib/integrations/connector/snapshot.js

@@ -1,6 +1,8 @@
-import { API_VERSION, HarnessError, contextDigest, digestOf, sha256, sourceDigest, workGraphDigest, workGraphSchema, } from "../../contracts/index.js";
+import { existsSync, statSync } from 'node:fs';
+import { API_VERSION, HarnessError, CONTEXT_LIMITS, contextDigest, contextIssues, digestOf, sha256, sourceDigest, workGraphDigest, workGraphSchema, } from "../../contracts/index.js";
 import { connectorIdOf, contextIdOf, graphIdOf, mappingDigest, orderIdOf, taskIdentity, } from "./config.js";
 import { TransportError, } from "./transport.js";
+import { FileContextSource } from "../../connectors/files.js";
 /** Безопасная причина отказа транспорта при чтении: сеть/CLI — не пустой список. */
 export function readFailure(error, what) {
     if (error instanceof HarnessError)
@@ -124,6 +126,8 @@ export function buildSnapshot(input) {
     const missing = [];
     const prerequisites = new Map();
     const tasks = [];
+    /** Какие локальные пакеты у какой задачи (по порядку): часть ревизии набора. */
+    const packsByTask = [];
     const truncated = [];
     let totalBytes = 0;
     const limits = config.limits;
@@ -331,8 +335,9 @@ export function buildSnapshot(input) {
             ...(mapping.gates ? { gates: mapping.gates } : {}),
             requirements: [],
             contracts: [],
-            context: [entry.id],
+            context: [entry.id, ...(mapping.context ?? [])],
         });
+        packsByTask.push([identityOf, mapping.context ?? []]);
         tasks.push({
             ref: mapping.ref,
             id: task.id,
@@ -367,6 +372,15 @@ export function buildSnapshot(input) {
         connector,
         tasks: tasks.map((t) => [t.identity, t.semanticDigest]),
         prerequisites: prereqs,
+        // Без локальных пакетов ревизия та же, что до их появления. С ними —
+        // содержимое пакетов и их распределение по задачам: перенос пакета между
+        // задачами или смена порядка — тоже новое согласование.
+        ...(input.local?.length || packsByTask.some(([, ids]) => ids.length)
+            ? {
+                context: (input.local ?? []).map((s) => [s.id, s.digest]),
+                contextBy: [...packsByTask].sort(([a], [b]) => (a < b ? -1 : 1)),
+            }
+            : {}),
     });
     const joined = `${config.provider}:${config.projectId}:${taskIds.join('+')}`;
     const graph = workGraphSchema.parse({
@@ -380,7 +394,15 @@ export function buildSnapshot(input) {
         orders,
         prerequisites: prereqs,
     });
-    const context = { apiVersion: API_VERSION, sources, missing };
+    const context = {
+        apiVersion: API_VERSION,
+        sources: [...sources, ...(input.local ?? [])],
+        missing,
+    };
+    // Пределы снимка контекста проверяются здесь, а не только при запуске:
+    // source-snapshot и source-check называют их как отказ eligibility.
+    for (const issue of contextLimitIssues(context))
+        problems.push({ code: 'LIMIT_EXCEEDED', taskId: '', key: 'context', message: issue });
     const manifest = {
         version: 1,
         provider: config.provider,
@@ -398,11 +420,45 @@ export function buildSnapshot(input) {
         tasks,
         truncated,
         problems,
+        ...(input.local?.length ? { localContext: input.local.map(localManifest) } : {}),
     };
     return { graph, context, manifest, revision, problems };
 }
+const CONTEXT_SOURCES_MAX = 30;
+/** Нарушения пределов снимка контекста: число источников, размер файла и сумма. */
+export function contextLimitIssues(context) {
+    const issues = contextIssues(context);
+    if (context.sources.length > CONTEXT_SOURCES_MAX)
+        issues.push(`Источников контекста ${context.sources.length} при пределе ${CONTEXT_SOURCES_MAX} (задачи и локальные пакеты)`);
+    return issues.map((i) => /больше предела/.test(i)
+        ? `${i} (fileBytes=${CONTEXT_LIMITS.fileBytes}, totalBytes=${CONTEXT_LIMITS.totalBytes})`
+        : i);
+}
+const localManifest = (s) => ({
+    id: s.id,
+    digest: s.digest,
+    files: s.files.length,
+    references: s.references.length,
+    bytes: [...s.files, ...s.references].reduce((n, f) => n + f.bytes, 0),
+});
+/**
+ * Локальные пакеты `tasks[].context` из `contextDir`: те же правила, что у
+ * файлового контекста графа (каталог `<contextDir>/<id>`, `references/` —
+ * справки). Нет каталога или пакета — NOT_READY до чтения backend.
+ */
+export async function localContext(config, contextDir) {
+    const ids = [...new Set(config.tasks.flatMap((t) => t.context ?? []))].sort();
+    if (!ids.length)
+        return [];
+    if (!contextDir)
+        throw new HarnessError('INVALID_INPUT', 'source: tasks[].context требует каталог пакетов (contextDir)');
+    if (!existsSync(contextDir) || !statSync(contextDir).isDirectory())
+        throw new HarnessError('NOT_READY', `Каталог пакетов контекста ${contextDir} не найден (tasks[].context: ${ids.join(', ')})`);
+    return (await new FileContextSource(contextDir).snapshot(ids)).sources;
+}
 /** Прочитать, собрать и проверить идентичность: общий путь `source-snapshot` и `run --source`. */
 export async function takeSnapshot(input) {
+    const local = await localContext(input.config, input.contextDir);
     const identity = await checkIdentity(input.transport, input.config, input.signal);
     const { reads, rounds } = await readStable(input.transport, input.config.tasks.map((t) => t.ref), input.config.limits.rereads, input.signal);
     return buildSnapshot({
@@ -411,6 +467,7 @@ export async function takeSnapshot(input) {
         reads,
         rounds,
         receiptOf: input.receiptOf,
+        ...(local.length ? { local } : {}),
     });
 }
 /** Отказ по eligibility/limits: причина и предел в сообщении, без запуска. */

package/lib/integrations/connector/source.d.ts

@@ -19,12 +19,16 @@ export declare class RelayWorkSource implements WorkSource {
         config: ConnectorConfig;
         transport: RelayTransport;
         store: ConnectorStore;
+        /** Абсолютный каталог пакетов `tasks[].context`. */
+        contextDir?: string;
     };
     readonly id: string;
     constructor(options: {
         config: ConnectorConfig;
         transport: RelayTransport;
         store: ConnectorStore;
+        /** Абсолютный каталог пакетов `tasks[].context`. */
+        contextDir?: string;
     });
     /** Снимок без проверки eligibility (для предпросмотра и диагностики). */
     snapshot(signal?: AbortSignal): Promise<BuiltSnapshot>;

package/lib/integrations/connector/source.js

@@ -26,6 +26,7 @@ export class RelayWorkSource {
             config: this.options.config,
             transport: this.options.transport,
             receiptOf: (orderId) => this.options.store.receipts(orderId).at(-1),
+            ...(this.options.contextDir ? { contextDir: this.options.contextDir } : {}),
             ...(signal ? { signal } : {}),
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devcontour-harness",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "description": "Headless execution harness: work graph, isolated attempts, gates, independent reviews and accepted results.",
   "type": "module",
   "license": "MIT",

package/skills/harness/SKILL.md

@@ -39,8 +39,10 @@ shasum -a 256 <file.tgz>
 ```
 
 Use the exact tarball (or exact registry version) you were given and record
-its sha256. Do not install it into the project: the project `package.json`
-and lockfile stay untouched.
+its sha256. Do not install it into the project's dependencies: the project
+`package.json` and lockfile stay untouched. `<tooldir>` is outside the
+repository or `<repo>/.harness-tools`; the `harness-setup` skill of the
+package covers both, the version pin and upgrades.
 
 ### 2. Check the machine
 
@@ -65,19 +67,19 @@ Schema of input and response, and the byte limits. Read only.
    interruption it resumes from the saved manifest decisions and writes only
    what is missing.
 
-| Conflict or refusal                                 | Meaning                                                                                              | Action                                                                                                                      |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `symlink`                                           | the path or an ancestor (`conflictPath`) is a symlink                                                | never write through it; the user replaces the link                                                                          |
-| `ancestor-not-directory`                            | an ancestor of the path is a file                                                                    | ask the user; never delete their files                                                                                      |
-| `not-regular-file`                                  | the destination exists and is not a regular file                                                     | ask the user                                                                                                                |
-| `outside-root`                                      | the destination resolves outside the repository                                                      | ask the user                                                                                                                |
-| `content-differs` on `.harness/project.json`        | an explicit `--writer` or `--profile` differs from the saved manifest                                | keep the saved decision, or the user confirms the change explicitly                                                         |
-| `content-differs` on `.harness/policy.json`         | the saved policy's writer differs from the manifest or explicit `--writer`                           | keep the saved decision, or the user confirms the change explicitly                                                         |
-| `INVALID_INPUT` with a path                         | not a Git root, invalid manifest or policy (also a truncated write), `--state` inside the repository | read the issue path; a broken file is removed by a human, not overwritten                                                   |
-| `NOT_READY` `no-commits`                            | the repository has no commits                                                                        | the user commits first                                                                                                      |
-| `NOT_READY` `stack-ambiguous` / `stack-unsupported` | both lockfiles, or none                                                                              | pass `--profile`; when profile gates do not fit, write `.harness/profile.json` and pass `--profile ./.harness/profile.json` |
-| `NOT_READY` toolchain problems                      | missing scripts, wrong tool versions                                                                 | fix the project or hand it to the user; never weaken the policy                                                             |
-| `CONTROLLER_BUSY`                                   | the repository is already owned by another controller                                                | stop: a second controller and state are not created                                                                         |
+| Conflict or refusal                                 | Meaning                                                                                                                                                 | Action                                                                                                                      |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `symlink`                                           | the path or an ancestor (`conflictPath`) is a symlink                                                                                                   | never write through it; the user replaces the link                                                                          |
+| `ancestor-not-directory`                            | an ancestor of the path is a file                                                                                                                       | ask the user; never delete their files                                                                                      |
+| `not-regular-file`                                  | the destination exists and is not a regular file                                                                                                        | ask the user                                                                                                                |
+| `outside-root`                                      | the destination resolves outside the repository                                                                                                         | ask the user                                                                                                                |
+| `content-differs` on `.harness/project.json`        | an explicit `--writer` or `--profile` differs from the saved manifest; after an upgrade or a move, also a changed built-in profile, root or API version | keep the saved decision, or the user confirms the change explicitly                                                         |
+| `content-differs` on `.harness/policy.json`         | the saved policy's writer differs from the manifest or explicit `--writer`                                                                              | keep the saved decision, or the user confirms the change explicitly                                                         |
+| `INVALID_INPUT` with a path                         | not a Git root, invalid manifest or policy (also a truncated write), `--state` inside the repository                                                    | read the issue path; a broken file is removed by a human, not overwritten                                                   |
+| `NOT_READY` `no-commits`                            | the repository has no commits                                                                                                                           | the user commits first                                                                                                      |
+| `NOT_READY` `stack-ambiguous` / `stack-unsupported` | both lockfiles, or none                                                                                                                                 | pass `--profile`; when profile gates do not fit, write `.harness/profile.json` and pass `--profile ./.harness/profile.json` |
+| `NOT_READY` toolchain problems                      | missing scripts, wrong tool versions                                                                                                                    | fix the project or hand it to the user; never weaken the policy                                                             |
+| `CONTROLLER_BUSY`                                   | the repository is already owned by another controller                                                                                                   | stop: a second controller and state are not created                                                                         |
 
 ### 4. Plan the graph