glirastes 0.4.0 → 0.5.0

package/dist/codegen/tools/routing-eval.js

@@ -0,0 +1,81 @@
+import { modelFacingToolName } from '../../runtime/local-tool-bindings.js';
+import { createToolSearchIndex } from '../../runtime/tool-search.js';
+import { compareCodeUnits } from './canonical.js';
+/** A sentence passes when its tool is among this many `find_tools` hits. */
+export const DEFAULT_ROUTING_TOP = 3;
+/**
+ * Deterministic routing check (spec 4.7 "Qualitätsschleife"): every example
+ * sentence of a tool must find that tool among the first `find_tools` hits,
+ * built exactly like the runtime index (name, description, module, shared
+ * modules, usage hints, synonyms), and the first hit must lie in the tool's
+ * module. No model, no network, no clock: the same outputs give the same
+ * bytes, so CI can run it as the FR-3 regression corpus.
+ */
+export function evaluateRouting(input) {
+    const top = Math.max(1, Math.trunc(input.top ?? DEFAULT_ROUTING_TOP));
+    const search = new Map(input.contracts.map((entry) => [entry.toolId, entry]));
+    const tools = input.artifact.tools
+        .filter((tool) => tool.enabled)
+        .map((tool) => ({ tool, modelName: tool.modelName ?? modelFacingToolName(tool.name), entry: search.get(tool.toolId) }))
+        .sort((left, right) => compareCodeUnits(left.tool.name, right.tool.name));
+    const byModelName = new Map(tools.map((item) => [item.modelName, item]));
+    const index = createToolSearchIndex(tools.map(({ tool, modelName, entry }) => ({
+        name: modelName,
+        description: tool.description ?? '',
+        ...(tool.module ? { module: tool.module } : {}),
+        sharedWith: tool.sharedWith ?? [],
+        usageHints: tool.usageHints ?? [],
+        synonyms: entry?.search?.synonyms ?? [],
+    })));
+    const results = [];
+    const withoutExamples = [];
+    let sentences = 0;
+    let failed = 0;
+    for (const { tool, modelName, entry } of tools) {
+        const examples = entry?.search?.examples ?? [];
+        if (examples.length === 0) {
+            withoutExamples.push(tool.name);
+            continue;
+        }
+        const failures = [];
+        for (const sentence of examples) {
+            sentences += 1;
+            const ranked = index.search(sentence, tools.length);
+            const position = ranked.indexOf(modelName);
+            const rank = position < 0 ? null : position + 1;
+            const first = ranked[0] === undefined ? undefined : byModelName.get(ranked[0]);
+            const moduleMismatch = first !== undefined && first.modelName !== modelName && first.tool.module !== tool.module;
+            if (rank !== null && rank <= top && !moduleMismatch)
+                continue;
+            failed += 1;
+            failures.push({
+                sentence,
+                rank,
+                competitors: ranked.slice(0, rank === null ? top : Math.min(rank - 1, top))
+                    .map((name) => byModelName.get(name)?.tool.name ?? name),
+                moduleMismatch,
+            });
+        }
+        results.push({
+            tool: tool.name,
+            stableKey: entry?.stableKey ?? tool.name,
+            module: tool.module ?? '',
+            sentences: examples.length,
+            failures,
+        });
+    }
+    return {
+        schemaVersion: 1,
+        top,
+        summary: {
+            tools: tools.length,
+            evaluated: results.length,
+            sentences,
+            passed: sentences - failed,
+            failed,
+            withoutExamples,
+        },
+        tools: results,
+    };
+}
+//# sourceMappingURL=routing-eval.js.map

package/dist/codegen/tools/routing-eval.js.map

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

package/dist/codegen/tools/schema-probe.d.ts

@@ -0,0 +1,62 @@
+import { type ToolPresentation } from '../../contracts/index.js';
+import type { DeclaredEffect } from '../../contracts/tool-policy.js';
+import type { JsonSchemaLike } from './types.js';
+export interface SchemaProbeItem {
+    kind: 'schema' | 'contract-entry';
+    io: 'input' | 'output';
+    module: string;
+    export: string;
+    property: string[];
+}
+export interface ProbedSchema {
+    ok: true;
+    kind: 'schema';
+    digest: string;
+    jsonSchema: JsonSchemaLike | null;
+    description: string | null;
+}
+/** Contract metadata fields that were declared but are unusable, so they read as `null`. */
+export type InvalidContractField = 'effect' | 'presentation';
+export interface ProbedContractEntry {
+    ok: true;
+    kind: 'contract-entry';
+    input: ProbedSchema;
+    output: ProbedSchema | null;
+    description: string | null;
+    effect: DeclaredEffect | null;
+    id: string | null;
+    module: string | null;
+    usageHints: string[] | null;
+    presentation: ToolPresentation | null;
+    /**
+     * Set only when the entry declares an `effect` outside the known set or a
+     * `presentation` that fails its schema; names the fields, never their
+     * values, so a typo can be told apart from an absent field.
+     */
+    invalidFields?: InvalidContractField[];
+    moduleDigest: string;
+}
+/**
+ * `content-rejected`: the schema, description or contract metadata carries a
+ * secret-looking string (content boundary), so nothing of it may be committed.
+ */
+export type ProbeFailureReason = 'missing' | 'import-failed' | 'not-a-schema' | 'invalid-entry' | 'content-rejected' | 'timeout' | 'probe-failed';
+export interface ProbeFailure {
+    ok: false;
+    reason: ProbeFailureReason;
+}
+export type SchemaProbeResult = ProbedSchema | ProbedContractEntry | ProbeFailure;
+export interface SchemaProbe {
+    probe(root: string, items: ReadonlyArray<SchemaProbeItem>): Promise<SchemaProbeResult[]>;
+}
+export declare const PROBE_TIMEOUT_MS = 10000;
+/**
+ * Imports exported schema modules in a child process: environment reduced to
+ * PATH/NODE_ENV/TZ, no shell, bounded time and output. A chunk that fails as
+ * a whole is retried module by module so one hanging module only costs itself.
+ * Results that carry a secret-looking string are rejected per item.
+ */
+export declare function createSchemaProbe(options?: {
+    timeoutMs?: number;
+    chunkSize?: number;
+}): SchemaProbe;

package/dist/codegen/tools/schema-probe.js

@@ -0,0 +1,209 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { ToolPresentationSchema } from '../../contracts/index.js';
+import { findSensitiveStringPath } from '../../contracts/content-boundary.js';
+import { sha256Digest, sortKeysDeep } from './canonical.js';
+export const PROBE_TIMEOUT_MS = 10_000;
+const CHUNK_SIZE = 25;
+const MAX_OUTPUT_CHARS = 8 * 1024 * 1024;
+const ENVIRONMENT_KEYS = ['PATH', 'NODE_ENV', 'TZ'];
+const DECLARED_EFFECTS = ['read', 'write', 'destructive', 'external', 'financial'];
+const WireSchema = z.object({
+    ok: z.literal(true),
+    kind: z.literal('schema'),
+    digest: z.string().regex(/^sha256:[A-Za-z0-9_-]{43}$/),
+    jsonSchema: z.record(z.string(), z.unknown()).nullable(),
+    description: z.string().nullable(),
+});
+const WireEntry = z.object({
+    ok: z.literal(true),
+    kind: z.literal('contract-entry'),
+    input: WireSchema,
+    output: WireSchema.nullable(),
+    description: z.string().nullable(),
+    effect: z.string().nullable(),
+    id: z.string().nullable(),
+    module: z.string().nullable(),
+    usageHints: z.array(z.string()).nullable(),
+    presentation: z.record(z.string(), z.unknown()).nullable(),
+});
+const WireFailure = z.object({
+    ok: z.literal(false),
+    reason: z.enum(['missing', 'import-failed', 'not-a-schema', 'invalid-entry']),
+});
+const WireOutput = z.object({ results: z.array(z.union([WireEntry, WireSchema, WireFailure])) });
+const CONTENT_REJECTED = Object.freeze({ ok: false, reason: 'content-rejected' });
+function scrubbedEnvironment() {
+    const env = {};
+    for (const key of ENVIRONMENT_KEYS) {
+        const value = process.env[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}
+function sdkLocations() {
+    const compiled = new URL('../../runtime/local-tool-bindings.js', import.meta.url);
+    const fromSource = !existsSync(fileURLToPath(compiled));
+    return {
+        digestModuleUrl: fromSource
+            ? new URL('../../runtime/local-tool-bindings.ts', import.meta.url).href
+            : compiled.href,
+        sdkSourceRoot: fromSource ? fileURLToPath(new URL('../../', import.meta.url)) : null,
+        typescriptUrl: pathToFileURL(createRequire(import.meta.url).resolve('typescript')).href,
+    };
+}
+function normalizeJson(value) {
+    if (!value)
+        return null;
+    const { $schema: _metaSchema, ...rest } = value;
+    return sortKeysDeep(rest);
+}
+function carriesSecret(value) {
+    return findSensitiveStringPath(value) !== null;
+}
+function toSchema(wire) {
+    const description = wire.description?.trim();
+    const schema = {
+        ok: true,
+        kind: 'schema',
+        digest: wire.digest,
+        jsonSchema: normalizeJson(wire.jsonSchema),
+        description: description ? description.slice(0, 1_000) : null,
+    };
+    return carriesSecret([schema.jsonSchema, schema.description]) ? CONTENT_REJECTED : schema;
+}
+function toEntry(wire) {
+    const input = toSchema(wire.input);
+    if (!input.ok)
+        return input;
+    const output = wire.output ? toSchema(wire.output) : null;
+    if (output && !output.ok)
+        return output;
+    const presentation = wire.presentation ? ToolPresentationSchema.safeParse(wire.presentation) : undefined;
+    const metadata = {
+        description: wire.description?.trim() ? wire.description.trim().slice(0, 1_000) : null,
+        effect: wire.effect && DECLARED_EFFECTS.includes(wire.effect) ? wire.effect : null,
+        id: wire.id?.trim() || null,
+        module: wire.module?.trim() || null,
+        usageHints: wire.usageHints
+            ? wire.usageHints.map((hint) => hint.trim()).filter(Boolean).slice(0, 20)
+            : null,
+        presentation: presentation?.success ? presentation.data : null,
+    };
+    if (carriesSecret(metadata))
+        return CONTENT_REJECTED;
+    const invalidFields = [];
+    if (wire.effect !== null && metadata.effect === null)
+        invalidFields.push('effect');
+    if (presentation && !presentation.success)
+        invalidFields.push('presentation');
+    return {
+        ok: true,
+        kind: 'contract-entry',
+        input,
+        output,
+        ...metadata,
+        ...(invalidFields.length > 0 ? { invalidFields } : {}),
+        moduleDigest: sha256Digest(JSON.stringify(sortKeysDeep({
+            input: input.digest,
+            output: output?.digest ?? null,
+            ...metadata,
+        }))),
+    };
+}
+function runChunk(root, items, timeoutMs) {
+    return new Promise((resolveResults) => {
+        let settled = false;
+        let output = '';
+        let timer;
+        const finish = (results) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolveResults(results);
+        };
+        const failAll = (reason) => finish(items.map(() => ({ ok: false, reason })));
+        const child = spawn(process.execPath, [fileURLToPath(new URL('./probe-child.mjs', import.meta.url))], {
+            cwd: root,
+            env: scrubbedEnvironment(),
+            shell: false,
+            // fd 3 carries the result; stdout stays out of the protocol because the
+            // imported app code may print to it at import time.
+            stdio: ['pipe', 'ignore', 'ignore', 'pipe'],
+        });
+        timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            failAll('timeout');
+        }, timeoutMs);
+        child.on('error', () => failAll('probe-failed'));
+        const resultStream = child.stdio[3];
+        resultStream.setEncoding('utf8');
+        resultStream.on('data', (chunk) => {
+            output += chunk;
+            if (output.length > MAX_OUTPUT_CHARS) {
+                child.kill('SIGKILL');
+                failAll('probe-failed');
+            }
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                failAll('probe-failed');
+                return;
+            }
+            const parsed = WireOutput.safeParse((() => {
+                try {
+                    return JSON.parse(output);
+                }
+                catch {
+                    return undefined;
+                }
+            })());
+            if (!parsed.success || parsed.data.results.length !== items.length) {
+                failAll('probe-failed');
+                return;
+            }
+            finish(parsed.data.results.map((result) => {
+                if (!result.ok)
+                    return { ok: false, reason: result.reason };
+                return result.kind === 'contract-entry' ? toEntry(result) : toSchema(result);
+            }));
+        });
+        const requestStream = child.stdin;
+        requestStream.on('error', () => failAll('probe-failed'));
+        requestStream.end(JSON.stringify({ appRoot: root, items, ...sdkLocations() }));
+    });
+}
+/**
+ * Imports exported schema modules in a child process: environment reduced to
+ * PATH/NODE_ENV/TZ, no shell, bounded time and output. A chunk that fails as
+ * a whole is retried module by module so one hanging module only costs itself.
+ * Results that carry a secret-looking string are rejected per item.
+ */
+export function createSchemaProbe(options = {}) {
+    const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+    const chunkSize = Math.max(1, options.chunkSize ?? CHUNK_SIZE);
+    return {
+        async probe(root, items) {
+            const results = [];
+            for (let index = 0; index < items.length; index += chunkSize) {
+                const chunk = items.slice(index, index + chunkSize);
+                const chunkResults = await runChunk(root, chunk, timeoutMs);
+                const wholeChunkFailed = chunk.length > 1 && chunkResults.every((result) => (!result.ok && (result.reason === 'timeout' || result.reason === 'probe-failed')));
+                if (!wholeChunkFailed) {
+                    results.push(...chunkResults);
+                    continue;
+                }
+                for (const item of chunk)
+                    results.push(...await runChunk(root, [item], timeoutMs));
+            }
+            return results;
+        },
+    };
+}
+//# sourceMappingURL=schema-probe.js.map

package/dist/codegen/tools/schema-probe.js.map

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

package/dist/codegen/tools/semantics.d.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import type { JsonSchemaLike, ToolFinding } from './types.js';
+/** Languages of synonyms, titles and example sentences (spec 4.7 "DE/EN"). */
+export declare const SEMANTICS_LANGUAGES: readonly ["de", "en"];
+export type SemanticsLanguage = typeof SEMANTICS_LANGUAGES[number];
+/** Fields of a `tool-semantics.json` entry that carry an origin and can be locked. */
+export declare const SEMANTICS_FIELDS: readonly ["description", "title", "module", "sharedWith", "usageHints", "presentation", "synonyms", "examples", "exampleCalls", "approvalHint"];
+export type SemanticsField = typeof SEMANTICS_FIELDS[number];
+export declare const SEMANTICS_LIMITS: {
+    readonly description: 1000;
+    readonly title: 200;
+    readonly hint: 500;
+    readonly hints: 20;
+    readonly synonym: 100;
+    readonly synonyms: 20;
+    readonly example: 200;
+    readonly examplesMin: 3;
+    readonly examplesMax: 5;
+    readonly exampleCalls: 10;
+    readonly approvalHint: 500;
+    readonly sharedWith: 50;
+};
+/**
+ * One entry of `.glirastes/tool-semantics.json` (spec 4.3, 4.7): the Get It
+ * Done format (`name`, `modelName`, `description`, `module`, `sharedWith`,
+ * `usageHints`, `presentation`) plus the stage-2 fields. A field without an
+ * origin was written by a human; `locked` pins reviewed fields by digest;
+ * `agent` names who wrote the agent fields and for which interface.
+ */
+export declare const SemanticsEntrySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    stableKey: z.ZodOptional<z.ZodString>;
+    modelName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    module: z.ZodOptional<z.ZodString>;
+    sharedWith: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    usageHints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    presentation: z.ZodOptional<z.ZodUnknown>;
+    title: z.ZodOptional<z.ZodObject<{
+        de: z.ZodOptional<z.ZodString>;
+        en: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    synonyms: z.ZodOptional<z.ZodObject<{
+        de: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        en: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    examples: z.ZodOptional<z.ZodObject<{
+        de: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        en: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    exampleCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        sentence: z.ZodOptional<z.ZodString>;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>>;
+    approvalHint: z.ZodOptional<z.ZodString>;
+    origin: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        module: "module";
+        description: "description";
+        sharedWith: "sharedWith";
+        usageHints: "usageHints";
+        presentation: "presentation";
+        title: "title";
+        synonyms: "synonyms";
+        examples: "examples";
+        exampleCalls: "exampleCalls";
+        approvalHint: "approvalHint";
+    }> & z.core.$partial, z.ZodEnum<{
+        code: "code";
+        agent: "agent";
+        human: "human";
+    }>>>;
+    locked: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        module: "module";
+        description: "description";
+        sharedWith: "sharedWith";
+        usageHints: "usageHints";
+        presentation: "presentation";
+        title: "title";
+        synonyms: "synonyms";
+        examples: "examples";
+        exampleCalls: "exampleCalls";
+        approvalHint: "approvalHint";
+    }> & z.core.$partial, z.ZodString>>;
+    agent: z.ZodOptional<z.ZodObject<{
+        model: z.ZodString;
+        interfaceDigest: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ToolSemanticsEntry = z.infer<typeof SemanticsEntrySchema>;
+/** Whether an agent wrote the entry or one of its fields; such entries get the unified check. */
+export declare function isAgenticSemantics(value: unknown): boolean;
+/** The app's language plus English, each once. */
+export declare function requiredLanguages(locale: string): SemanticsLanguage[];
+export interface SemanticsCheckContext {
+    stableKey: string;
+    /** Interface the tool has now; an agent entry for another one is stale. */
+    interfaceDigest?: string;
+    /** The tool's input JSON Schema; example calls must satisfy it. */
+    input?: JsonSchemaLike;
+}
+export interface SemanticsCheck {
+    entry?: ToolSemanticsEntry;
+    findings: ToolFinding[];
+    /** An agent entry written for an earlier interface: still used, listed for renewal. */
+    stale: boolean;
+    /** Example calls of a stale entry the current input schema refuses; left out of `entry`. */
+    droppedExampleCalls?: number;
+}
+/**
+ * The unified check of one semantics entry against the tool it describes
+ * (spec 4.6, 4.7). Locked fields must still match their digest and never be
+ * marked as agent output. No entry may carry secrets, provider keys or
+ * control characters: `origin` is the writer's own claim, and synonyms reach
+ * the generated module. An agent entry must also name its model and
+ * interface, stay within the prose and length limits and give example calls
+ * that the tool's input schema accepts. A rejected entry is ignored and
+ * reported. An agent entry for an earlier interface stays in use and is
+ * listed for renewal; its example calls were written for the old schema, so
+ * the ones the current schema refuses are left out instead of rejecting it.
+ */
+export declare function validateSemanticsEntry(entry: ToolSemanticsEntry, context: SemanticsCheckContext): SemanticsCheck;
+export interface SemanticsFacts {
+    /** Fields a human wrote, the code supplied or a review locked; an agent never replaces them. */
+    protectedFields: SemanticsField[];
+    hasSynonyms: boolean;
+    /** Required languages without 3–5 example sentences. */
+    missingExamples: SemanticsLanguage[];
+}
+export declare function semanticsFacts(entry: ToolSemanticsEntry | undefined, languages: ReadonlyArray<SemanticsLanguage>): SemanticsFacts;
+/** Synonyms and example sentences of both languages, each once, in code-unit order. */
+export declare function semanticsSearch(entry: ToolSemanticsEntry | undefined): {
+    synonyms: string[];
+    examples: string[];
+};