@shrkcrft/ai 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/delegate/delegate-edit-schema.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The structured edit a delegate worker (local LLM) is asked to emit.
+ *
+ * This layer (`@shrkcrft/ai`) sits BELOW `@shrkcrft/generator`, so it cannot
+ * reference `IPlannedOperation`. The worker's output is therefore parsed into a
+ * deliberately-RAW shape here: `operation` is `{ kind } & Record<string,
+ * unknown>`. The generator-layer packager (`packageDelegatePlan`) is the
+ * authority that validates each raw op against the real operation union and the
+ * recipe's `allowedOps` — a raw op never writes anything on its own.
+ */
+/** One raw operation the worker wants to apply to a file. */
+export interface IDelegateRawOp {
+    /** File path the op targets, relative to the project root. */
+    targetPath: string;
+    /**
+     * The operation intent. `kind` selects an `IPlannedOperation` variant; the
+     * remaining fields are validated against that variant downstream, never here.
+     */
+    operation: {
+        kind: string;
+    } & Record<string, unknown>;
+}
+/** The full structured edit returned by a delegate worker. */
+export interface IDelegateRawEdit {
+    ops: readonly IDelegateRawOp[];
+    /** Optional free-form note from the worker. Informational only; not applied. */
+    note?: string;
+}
+/**
+ * `IPlannedOperation` kinds a delegate worker may emit. Hardcoded here (not
+ * imported from the higher generator layer) — this is a HINT for the model's
+ * `json_schema` response format, not the security boundary. The generator's
+ * `packageDelegatePlan` + the recipe's `allowedOps` are the real gate, so a
+ * kind missing here only makes the model less likely to emit it.
+ */
+export declare const DELEGATE_OP_KINDS: readonly string[];
+/**
+ * JSON Schema handed to the provider as `responseFormat.schema` so a local
+ * model returns a parseable edit. `operation` allows extra properties on
+ * purpose — different op kinds carry different fields, and the generator
+ * validates the exact shape per kind.
+ */
+export declare const DELEGATE_EDIT_JSON_SCHEMA: Record<string, unknown>;
+//# sourceMappingURL=delegate-edit-schema.d.ts.map

package/dist/delegate/delegate-edit-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-edit-schema.d.ts","sourceRoot":"","sources":["../../src/delegate/delegate-edit-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvD;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,SAAS,cAAc,EAAE,CAAC;IAC/B,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAa9C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAuC7D,CAAC"}

package/dist/delegate/delegate-edit-schema.js

@@ -0,0 +1,77 @@
+/**
+ * The structured edit a delegate worker (local LLM) is asked to emit.
+ *
+ * This layer (`@shrkcrft/ai`) sits BELOW `@shrkcrft/generator`, so it cannot
+ * reference `IPlannedOperation`. The worker's output is therefore parsed into a
+ * deliberately-RAW shape here: `operation` is `{ kind } & Record<string,
+ * unknown>`. The generator-layer packager (`packageDelegatePlan`) is the
+ * authority that validates each raw op against the real operation union and the
+ * recipe's `allowedOps` — a raw op never writes anything on its own.
+ */
+/**
+ * `IPlannedOperation` kinds a delegate worker may emit. Hardcoded here (not
+ * imported from the higher generator layer) — this is a HINT for the model's
+ * `json_schema` response format, not the security boundary. The generator's
+ * `packageDelegatePlan` + the recipe's `allowedOps` are the real gate, so a
+ * kind missing here only makes the model less likely to emit it.
+ */
+export const DELEGATE_OP_KINDS = [
+    'create',
+    'append',
+    'insert-after',
+    'insert-before',
+    'replace',
+    'export',
+    'ensure-import',
+    'insert-enum-entry',
+    'insert-object-entry',
+    'insert-array-entry',
+    'insert-before-closing-brace',
+    'insert-between-anchors',
+];
+/**
+ * JSON Schema handed to the provider as `responseFormat.schema` so a local
+ * model returns a parseable edit. `operation` allows extra properties on
+ * purpose — different op kinds carry different fields, and the generator
+ * validates the exact shape per kind.
+ */
+export const DELEGATE_EDIT_JSON_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['ops'],
+    properties: {
+        note: { type: 'string' },
+        ops: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['targetPath', 'operation'],
+                properties: {
+                    targetPath: {
+                        type: 'string',
+                        description: 'file path relative to the project root',
+                    },
+                    operation: {
+                        type: 'object',
+                        additionalProperties: true,
+                        required: ['kind'],
+                        properties: {
+                            kind: { type: 'string', enum: [...DELEGATE_OP_KINDS] },
+                            from: { type: 'string', description: 'module specifier (export / ensure-import)' },
+                            symbols: { type: 'array', items: { type: 'string' } },
+                            typeOnly: { type: 'boolean' },
+                            find: { type: 'string' },
+                            replaceWith: { type: 'string' },
+                            expectMatches: { type: 'number' },
+                            content: { type: 'string' },
+                            snippet: { type: 'string' },
+                            anchor: { type: 'string' },
+                            ifMissing: { type: 'string' },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};

package/dist/delegate/parse-delegate-edit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Parse + (lightly) validate the JSON a delegate worker emits, and a one-shot
+ * generate→parse→reprompt-once helper. Mirrors the smart-context provider call
+ * pattern (`callProviderWithRetry`): a PARSE failure reprompts once; a provider
+ * / TIMEOUT error surfaces immediately (the orchestrator owns macro-retries).
+ */
+import { type AppError, type Result } from '@shrkcrft/core';
+import type { IAiProvider } from '../ai-provider.js';
+import { type IAiMessage } from '../ai-request.js';
+import { type IDelegateRawEdit } from './delegate-edit-schema.js';
+/** Parse a worker's raw output into a structurally-validated `IDelegateRawEdit`. */
+export declare function parseDelegateEdit(raw: string): Result<IDelegateRawEdit, AppError>;
+export interface IDelegateCallInput {
+    provider: IAiProvider;
+    messages: readonly IAiMessage[];
+    model?: string;
+    /** Per-call wall-clock budget; a TIMEOUT surfaces immediately (no retry). */
+    timeoutMs?: number;
+    maxTokens?: number;
+    /**
+     * Build the reprompt messages after a PARSE failure. Receives the model's bad
+     * output + the parse error. When omitted, a parse failure is returned as-is.
+     */
+    reprompt?: (badOutput: string, error: AppError) => readonly IAiMessage[];
+}
+export interface IDelegateCallResult {
+    edit: IDelegateRawEdit;
+    /** The raw model output that parsed (for telemetry / hand-back). */
+    raw: string;
+    model: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    /** True when the first output failed to parse and the reprompt succeeded. */
+    retried: boolean;
+}
+/**
+ * Generate a delegate edit, parsing the output. A provider / TIMEOUT error
+ * surfaces immediately; a PARSE failure reprompts ONCE (when a reprompt builder
+ * is supplied) before giving up.
+ */
+export declare function callDelegateWithRetry(input: IDelegateCallInput): Promise<Result<IDelegateCallResult, AppError>>;
+/** Convenience for callers building reprompt messages. */
+export declare function delegateRepromptMessage(badOutput: string, error: AppError): IAiMessage;
+//# sourceMappingURL=parse-delegate-edit.d.ts.map

package/dist/delegate/parse-delegate-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-delegate-edit.d.ts","sourceRoot":"","sources":["../../src/delegate/parse-delegate-edit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAA6B,KAAK,gBAAgB,EAAuB,MAAM,2BAA2B,CAAC;AAgBlH,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CA0CjF;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,KAAK,SAAS,UAAU,EAAE,CAAC;CAC1E;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,gBAAgB,CAAC;IACvB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;CAClB;AAkBD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC,CA0BhD;AAED,0DAA0D;AAC1D,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,UAAU,CAQtF"}

package/dist/delegate/parse-delegate-edit.js

@@ -0,0 +1,128 @@
+/**
+ * Parse + (lightly) validate the JSON a delegate worker emits, and a one-shot
+ * generate→parse→reprompt-once helper. Mirrors the smart-context provider call
+ * pattern (`callProviderWithRetry`): a PARSE failure reprompts once; a provider
+ * / TIMEOUT error surfaces immediately (the orchestrator owns macro-retries).
+ */
+import { AppErrorImpl, ERROR_CODES, err, ok, } from '@shrkcrft/core';
+import { AiMessageRole } from "../ai-request.js";
+import { DELEGATE_EDIT_JSON_SCHEMA } from "./delegate-edit-schema.js";
+function invalid(message, cause) {
+    return new AppErrorImpl(ERROR_CODES.INVALID_INPUT, message, cause !== undefined ? { cause } : undefined);
+}
+/**
+ * Strip a leading/trailing markdown code fence (```json … ```), which weak
+ * local models often wrap JSON in despite a json_schema response format.
+ */
+function stripFences(text) {
+    const fence = /^\s*```(?:json)?\s*\n([\s\S]*?)\n```\s*$/;
+    const m = text.match(fence);
+    return m ? m[1] : text;
+}
+/** Parse a worker's raw output into a structurally-validated `IDelegateRawEdit`. */
+export function parseDelegateEdit(raw) {
+    const text = stripFences(raw).trim();
+    if (text.length === 0)
+        return err(invalid('delegate edit is empty'));
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        return err(invalid('delegate edit is not valid JSON', e));
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return err(invalid('delegate edit must be a JSON object'));
+    }
+    const obj = parsed;
+    const opsRaw = obj['ops'];
+    if (!Array.isArray(opsRaw))
+        return err(invalid('delegate edit "ops" must be an array'));
+    const ops = [];
+    for (let i = 0; i < opsRaw.length; i += 1) {
+        const o = opsRaw[i];
+        if (!o || typeof o !== 'object' || Array.isArray(o)) {
+            return err(invalid(`ops[${i}] must be an object`));
+        }
+        const oo = o;
+        const targetPath = oo['targetPath'];
+        if (typeof targetPath !== 'string' || targetPath.trim().length === 0) {
+            return err(invalid(`ops[${i}].targetPath must be a non-empty string`));
+        }
+        const operation = oo['operation'];
+        if (!operation || typeof operation !== 'object' || Array.isArray(operation)) {
+            return err(invalid(`ops[${i}].operation must be an object`));
+        }
+        const kind = operation['kind'];
+        if (typeof kind !== 'string' || kind.length === 0) {
+            return err(invalid(`ops[${i}].operation.kind must be a non-empty string`));
+        }
+        ops.push({
+            targetPath,
+            operation: operation,
+        });
+    }
+    const edit = { ops };
+    if (typeof obj['note'] === 'string')
+        edit.note = obj['note'];
+    return ok(edit);
+}
+async function sendOnce(input, messages) {
+    if (input.model)
+        input.provider.configure({ model: input.model });
+    const res = await input.provider.send({
+        messages,
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.maxTokens ? { maxTokens: input.maxTokens } : {}),
+        ...(input.timeoutMs ? { timeoutMs: input.timeoutMs } : {}),
+        responseFormat: { type: 'json_schema', schema: DELEGATE_EDIT_JSON_SCHEMA, schemaName: 'DelegateEdit' },
+    });
+    if (!res.ok)
+        return res;
+    return ok({ content: res.value.content, model: res.value.model, ...(res.value.usage ? { usage: res.value.usage } : {}) });
+}
+/**
+ * Generate a delegate edit, parsing the output. A provider / TIMEOUT error
+ * surfaces immediately; a PARSE failure reprompts ONCE (when a reprompt builder
+ * is supplied) before giving up.
+ */
+export async function callDelegateWithRetry(input) {
+    const first = await sendOnce(input, input.messages);
+    if (!first.ok)
+        return first;
+    const parsed = parseDelegateEdit(first.value.content);
+    if (parsed.ok) {
+        return ok({
+            edit: parsed.value,
+            raw: first.value.content,
+            model: first.value.model,
+            ...(first.value.usage ? { usage: first.value.usage } : {}),
+            retried: false,
+        });
+    }
+    if (!input.reprompt)
+        return err(parsed.error);
+    const retryMessages = input.reprompt(first.value.content, parsed.error);
+    const second = await sendOnce(input, retryMessages);
+    if (!second.ok)
+        return second;
+    const reparsed = parseDelegateEdit(second.value.content);
+    if (!reparsed.ok)
+        return err(reparsed.error);
+    return ok({
+        edit: reparsed.value,
+        raw: second.value.content,
+        model: second.value.model,
+        ...(second.value.usage ? { usage: second.value.usage } : {}),
+        retried: true,
+    });
+}
+/** Convenience for callers building reprompt messages. */
+export function delegateRepromptMessage(badOutput, error) {
+    return {
+        role: AiMessageRole.User,
+        content: `Your previous reply could not be parsed: ${error.message}\n` +
+            `It must be a single JSON object matching the schema — no prose, no markdown fences.\n` +
+            `Previous reply was:\n${badOutput.slice(0, 2000)}`,
+    };
+}

package/dist/index.d.ts

@@ -10,4 +10,6 @@ export * from './provider-resolver.js';
 export * from './pipeline/enhancement-pipeline.js';
 export * from './llm-hints.js';
 export * from './llm-recommendations.js';
+export * from './delegate/delegate-edit-schema.js';
+export * from './delegate/parse-delegate-edit.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC;AACnD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC;AACnD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC"}

package/dist/index.js

@@ -10,3 +10,5 @@ export * from "./provider-resolver.js";
 export * from "./pipeline/enhancement-pipeline.js";
 export * from "./llm-hints.js";
 export * from "./llm-recommendations.js";
+export * from "./delegate/delegate-edit-schema.js";
+export * from "./delegate/parse-delegate-edit.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/ai",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "description": "SharkCraft local LLM provider abstraction: Ollama (HTTP) + llama.cpp (in-process) + multi-pass enhancement pipeline.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,8 +43,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.16",
-    "@shrkcrft/context": "^0.1.0-alpha.16",
+    "@shrkcrft/core": "^0.1.0-alpha.18",
+    "@shrkcrft/context": "^0.1.0-alpha.18",
     "node-llama-cpp": "^3.16.0"
   },
   "publishConfig": {