@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/kernel/profile-presence.js

@@ -0,0 +1,143 @@
+// Leaf module: `schema.ts` reads it at load time. `defineProfile` enforces the requirements;
+// this records them for display.
+/** Presence for profile paths, keyed like `PROFILE_FIELDS` (`models.*` matches every binding). */
+export const PROFILE_FIELD_PRESENCE = {
+    id: { required: true },
+    type: { required: true },
+    identity: { required: true },
+    'identity.handle': { required: true },
+    'identity.system': { unset: 'No system instruction' },
+    tools: { required: true },
+    'tools.allow': { required: true },
+    image: { required: true },
+    speech: { required: true },
+    live: { required: true },
+    decision: { required: true },
+    'decision.contract': { required: true },
+    models: { required: true },
+    defaultModel: { required: 'when more than one model is declared', unset: 'The only model' },
+    allowModelSelect: { unset: 'Off' },
+    maxSteps: { unset: 'Unbounded' },
+    key: { required: 'when a Google model has no key of its own', unset: 'No key slot' },
+    fallbackKey: { unset: 'No fallback' },
+    'models.*.protocol': { required: true },
+    'models.*.provider': { required: true },
+    'models.*.apiId': { required: true },
+    'models.*.builtInTools': { unset: 'None' },
+    'models.*.maxOutputTokens': { unset: 'Provider default' },
+    'models.*.temperature': { unset: 'Provider default' },
+    'models.*.summaries': { unset: 'Provider default' },
+    'models.*.efforts': { unset: 'Provider default' },
+    'models.*.defaultEffort': {
+        required: 'when more than one effort is declared',
+        unset: 'The only effort',
+    },
+    'models.*.allowEffortSelect': { unset: 'Off' },
+    'models.*.key': { unset: "The profile's key" },
+    'models.*.fallbackKey': { unset: "The profile's fallback key" },
+    'models.*.timeoutMs': { unset: 'No timeout' },
+    'models.*.compaction': { unset: 'Off' },
+    'models.*.compaction.maxTokens': { required: true },
+    'models.*.compaction.compactAt': { required: true },
+    'models.*.compaction.previousExchanges': { required: true },
+    'models.*.compaction.profile': { unset: 'The agent itself' },
+    'models.*.compaction.timing': { required: true },
+    'models.*.compaction.meter': { unset: 'history' },
+    'models.*.cache': { unset: 'Off' },
+    'models.*.cache.mode': { required: true },
+    'models.*.cache.ttl': { unset: 'Provider default' },
+    'models.*.store': { unset: 'Provider default' },
+    'models.*.persistViaInteractionId': { required: 'when the protocol is geminiInteractions' },
+    inputs: { required: true },
+    'inputs.text': { unset: 'Accepted' },
+    'inputs.attachments.accept': { unset: 'No attachments' },
+    'inputs.voice.accept': { unset: 'No voice' },
+    'inputs.maxFiles': { required: 'when attachments or voice is set' },
+    'inputs.maxBytes': { required: 'when attachments or voice is set' },
+    'inputs.maxTurnBytes': { required: 'when attachments or voice is set' },
+    'inputs.state': { required: true },
+    'inputs.maxStateBytes': { unset: 'No cap' },
+    'inputs.limitsByMime': { unset: 'maxBytes for every type' },
+    'inputs.slots': { unset: 'No slots' },
+    'outputs.structured': { unset: 'Free text' },
+    'outputs.validation.maxRetries': { unset: '0' },
+    'outputs.streaming.mode': { unset: 'sse' },
+    'outputs.streaming.streamThoughts': { unset: 'On' },
+    'turnBehaviour.resumption.allowContinue': { unset: 'All three' },
+    'turnBehaviour.resumption.autoContinue': { unset: 'length and stream_incomplete' },
+    'turnBehaviour.resumption.maxContinues': { unset: 'No cap' },
+    'turnBehaviour.allowSteering': { unset: 'On' },
+    'guardrails.quota': { unset: 'No limit' },
+    'guardrails.canary': { unset: 'On' },
+    'guardrails.sanitizeInput': { unset: 'On' },
+    'guardrails.redactSensitive': { unset: 'On' },
+    'guardrails.egress': { unset: 'No check' },
+    'guardrails.egress.enforce': { required: 'when checks is not set' },
+    'guardrails.egress.checks': { required: 'when enforce is not set' },
+    'guardrails.egress.checks.sensitive': { unset: 'Every group but network' },
+    'guardrails.egress.checks.sensitive.ids': { unset: 'On' },
+    'guardrails.egress.checks.sensitive.financial': { unset: 'On' },
+    'guardrails.egress.checks.sensitive.network': { unset: 'Off' },
+    'guardrails.egress.checks.sensitive.credentials': { unset: 'On' },
+    'guardrails.egress.checks.boundary': { unset: 'On' },
+    'guardrails.egress.checks.injection': { unset: 'On' },
+    'guardrails.egress.checks.images': { unset: 'On' },
+    'guardrails.egress.checks.images.hosts': { unset: 'None' },
+    'guardrails.egress.checks.images.fromTools': { unset: 'On' },
+    'guardrails.egress.checks.links': { unset: 'Off' },
+    'guardrails.egress.checks.links.hosts': { unset: 'The images hosts' },
+    'guardrails.egress.checks.links.fromTools': { unset: 'On' },
+    'guardrails.egress.onBlock': { unset: 'reject_to_agent' },
+    'guardrails.egress.maxRetries': { unset: '0' },
+    'guardrails.egress.holdback': { unset: '256' },
+    'guardrails.network.allowPrivateNetworks': { unset: 'Off' },
+    'guardrails.network.allowedHosts': { unset: 'None' },
+    'guardrails.network.allowedSchemes': {
+        unset: 'https, plus http when allowPrivateNetworks is on',
+    },
+    'guardrails.taint.afterRemoteRead': { unset: 'off' },
+    'guardrails.disclosure': { unset: 'No check' },
+    'observability.writeTo': { unset: 'No traces' },
+    'observability.sampleRate': { unset: '1' },
+    'observability.include.upstreamLog': { unset: 'On' },
+    'observability.include.outboundWire': { unset: 'Off' },
+    'observability.include.evidenceRaw': { unset: 'Off' },
+    'observability.include.usage': { unset: 'On' },
+    'observability.include.guardrailDecisions': { unset: 'On' },
+    'observability.include.guardrailMatchPreview': { unset: 'Off' },
+    'observability.resource': { unset: 'None' },
+    'observability.scrub.sensitive': { unset: 'On' },
+    'observability.scrub.injection': { unset: 'On' },
+    'observability.scrub.canary': { unset: 'On' },
+    'observability.retainForDays': { unset: '14' },
+    'observability.rotateAfterMiB': { unset: '32' },
+    'observability.onWriteError': { unset: 'Errors are dropped' },
+    'image.aspectRatio': { unset: 'Provider default' },
+    'image.resolution': { unset: 'Provider default' },
+    'image.mimeType': { unset: 'Provider default' },
+    'image.quality': { unset: 'Provider default' },
+    'image.background': { unset: 'Provider default' },
+    'image.n': { unset: 'Provider default' },
+    'image.seed': { unset: 'Provider default' },
+    'image.outputCompression': { unset: 'Provider default' },
+    'image.references': { unset: 'None' },
+    'image.includeText': { unset: 'Off' },
+    'speech.voice': { unset: 'Provider default' },
+    'speech.format': { unset: 'Provider default' },
+    'live.ingress.audio': { unset: 'On' },
+    'live.ingress.video': { unset: 'On' },
+    'live.ingress.text': { unset: 'Off' },
+    'live.voice': { unset: 'Provider default' },
+    'live.vad.activityHandling': { unset: 'Provider default' },
+    'live.vad.startSensitivity': { unset: 'Provider default' },
+    'live.vad.endSensitivity': { unset: 'Provider default' },
+    'live.vad.prefixPaddingMs': { unset: 'Provider default' },
+    'live.vad.silenceDurationMs': { unset: 'Provider default' },
+    'live.sessionResumption': { unset: 'Off' },
+    'live.contextCompression': { unset: 'Off' },
+    'live.contextCompression.triggerTokens': { unset: 'Provider default' },
+    'live.contextCompression.slidingWindow': { required: true },
+    'live.contextCompression.slidingWindow.targetTokens': { unset: 'Provider default' },
+    'live.transcription.input': { unset: 'Off' },
+    'live.transcription.output': { unset: 'Off' },
+};

package/esm/src/kernel/profile-scope.d.ts

@@ -0,0 +1,36 @@
+import type { ProfileType } from './schema.js';
+/**
+ * Mirrors `PROFILE_TYPES` — a value import would cycle through `schema.ts`.
+ * Drift is gated by tests/kernel/profile-scope.test.ts.
+ */
+export declare const ALL_PROFILE_TYPES: readonly ProfileType[];
+export interface ProfileFieldScope {
+    profileTypes: readonly ProfileType[];
+    /** Why other types can't take it — shown in `defineProfile` errors and authoring UIs. */
+    reason: string;
+    /**
+     * The one value other types may still carry: the field's "off" value (speech stores
+     * `guardrails.canary: false`; `outputs.structured: null` asks for no schema).
+     */
+    offValue?: false | null;
+}
+/** Keyed like `PROFILE_FIELDS`; `models.*` matches every model binding. */
+export declare const PROFILE_FIELD_SCOPE: Readonly<Record<string, ProfileFieldScope>>;
+/**
+ * The scope entry that governs `path`: its own, else its nearest ancestor's.
+ * `undefined` means every profile type.
+ */
+export declare function profileFieldScope(path: string): ProfileFieldScope | undefined;
+export declare function profileTypesForField(path: string): readonly ProfileType[];
+export interface OutOfScopeField {
+    /** e.g. `models.fast.compaction` for the `models.*.compaction` scope. */
+    path: string;
+    scope: ProfileFieldScope;
+}
+/**
+ * Every field `profile` sets that its type may not, ancestors before their
+ * children. A scope's off value is not reported.
+ */
+export declare function outOfScopeFields(profile: {
+    readonly type: ProfileType;
+}): OutOfScopeField[];

package/esm/src/kernel/profile-scope.js

@@ -0,0 +1,262 @@
+// Leaf module: `schema.ts` and `profile-graph.ts` read it at load time.
+/** lexicon-exempt-file: authoring field-meta scope reasons — not runtime user or model copy (P2) */
+import { HOST_GUARDRAIL_FIELDS } from '../guardrails/types.js';
+/**
+ * Mirrors `PROFILE_TYPES` — a value import would cycle through `schema.ts`.
+ * Drift is gated by tests/kernel/profile-scope.test.ts.
+ */
+export const ALL_PROFILE_TYPES = [
+    'text',
+    'image',
+    'speech',
+    'live',
+    'decision',
+    'host',
+];
+const MODEL_PROFILE_TYPES = ['text', 'image', 'speech', 'live', 'decision'];
+const TURN_TYPES = ['text', 'image', 'speech', 'live'];
+/** Types whose `inputs` are turn inputs (text, files, slots) rather than decision state. */
+const TURN_INPUT_TYPES = ['text', 'image'];
+const TURN_INPUT_REASON = 'a decision takes JSON state, not turn text, files or slots';
+/** Guardrails a host profile may set keep `host`; the rest guard a model turn. */
+function turnGuardrailTypes(key) {
+    return HOST_GUARDRAIL_FIELDS.includes(key)
+        ? [...TURN_TYPES, 'host']
+        : TURN_TYPES;
+}
+/** Keyed like `PROFILE_FIELDS`; `models.*` matches every model binding. */
+export const PROFILE_FIELD_SCOPE = {
+    ...Object.fromEntries([
+        'efforts',
+        'defaultEffort',
+        'allowEffortSelect',
+        'summaries',
+        'maxOutputTokens',
+        'temperature',
+        'builtInTools',
+        'cache',
+        'store',
+        'persistViaInteractionId',
+        'server',
+        'fallbackKey',
+    ].map((field) => [
+        `models.*.${field}`,
+        {
+            profileTypes: TURN_TYPES,
+            reason: 'only model turns use this setting; decisions send state and questions',
+        },
+    ])),
+    'models.*.timeoutMs': {
+        profileTypes: ['decision'],
+        reason: 'only decision bindings configure a request timeout here',
+    },
+    identity: {
+        profileTypes: MODEL_PROFILE_TYPES,
+        reason: 'a host profile has no agent identity — it runs no model',
+    },
+    'identity.system': {
+        profileTypes: ['text', 'image', 'live'],
+        reason: 'speech has no system channel (the input text is the transcript) and a decision is asked only through its questions',
+    },
+    'identity.systemByRole': {
+        profileTypes: ['text', 'image', 'live'],
+        reason: 'speech has no system channel (the input text is the transcript) and a decision is asked only through its questions',
+    },
+    models: { profileTypes: MODEL_PROFILE_TYPES, reason: 'a host profile runs no model' },
+    'models.*.protocol': {
+        profileTypes: MODEL_PROFILE_TYPES,
+        reason: 'a host profile runs no model',
+    },
+    'models.*.provider': {
+        profileTypes: MODEL_PROFILE_TYPES,
+        reason: 'a host profile runs no model',
+    },
+    'models.*.compaction': {
+        profileTypes: ['text', 'image', 'speech'],
+        reason: 'live compacts with live.contextCompression',
+    },
+    key: { profileTypes: MODEL_PROFILE_TYPES, reason: 'a host profile runs no model' },
+    fallbackKey: {
+        profileTypes: TURN_TYPES,
+        reason: 'a host profile runs no model and a decision makes one call on its key',
+    },
+    defaultModel: {
+        profileTypes: TURN_TYPES,
+        reason: 'a host profile runs no model and a decision declares exactly one',
+    },
+    allowModelSelect: {
+        profileTypes: TURN_TYPES,
+        reason: 'a host profile runs no model and a decision declares exactly one',
+    },
+    maxSteps: {
+        profileTypes: TURN_TYPES,
+        reason: 'only model turns take tool-loop steps',
+    },
+    decision: { profileTypes: ['decision'], reason: 'only decision profiles carry a contract' },
+    image: { profileTypes: ['image'], reason: 'only image profiles generate images' },
+    speech: { profileTypes: ['speech'], reason: 'only speech profiles synthesize audio' },
+    live: { profileTypes: ['live'], reason: 'only live profiles open a realtime session' },
+    tools: {
+        profileTypes: ['text', 'image', 'live', 'host'],
+        reason: 'speech and decision profiles call no tools',
+    },
+    'tools.t1Policy': {
+        profileTypes: ['text', 'image'],
+        reason: 'live wires every allowed tool once at session setup, and a host profile can execute every allowed tool',
+    },
+    'tools.t2Loader': {
+        profileTypes: ['text', 'image'],
+        reason: 'live function declarations are fixed at session setup, and a host profile can execute every allowed tool',
+    },
+    inputs: {
+        profileTypes: ['text', 'image', 'decision'],
+        reason: 'speech input is the transcript, live ingress is live.ingress, and a host profile takes no turns',
+    },
+    'inputs.voice': {
+        profileTypes: ['text'],
+        reason: 'no image model reads audio, and a decision takes JSON state',
+    },
+    'inputs.text': {
+        profileTypes: TURN_INPUT_TYPES,
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.attachments': {
+        profileTypes: TURN_INPUT_TYPES,
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.maxFiles': {
+        profileTypes: TURN_INPUT_TYPES,
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.maxBytes': {
+        profileTypes: TURN_INPUT_TYPES,
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.maxTurnBytes': {
+        profileTypes: TURN_INPUT_TYPES,
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.limitsByMime': {
+        profileTypes: TURN_INPUT_TYPES,
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.slots': {
+        profileTypes: TURN_INPUT_TYPES,
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.state': {
+        profileTypes: ['decision'],
+        reason: 'only a decision reads JSON state; a turn takes text, files and slots',
+    },
+    'inputs.maxStateBytes': {
+        profileTypes: ['decision'],
+        reason: 'only a decision reads JSON state; a turn takes text, files and slots',
+    },
+    outputs: {
+        profileTypes: ['text', 'image', 'speech'],
+        reason: 'live output is the realtime session, and decision and host profiles produce no turn output',
+    },
+    'outputs.structured': {
+        profileTypes: ['text'],
+        reason: 'only a text reply has a JSON shape; image and speech turns return media',
+        offValue: null,
+    },
+    'outputs.validation': {
+        profileTypes: ['text'],
+        reason: 'validation checks a structured reply, which only text profiles make',
+    },
+    turnBehaviour: {
+        profileTypes: TURN_TYPES,
+        reason: 'only model turns can be continued or steered',
+    },
+    'turnBehaviour.resumption': {
+        profileTypes: ['text', 'image', 'speech'],
+        reason: 'live resumes through live.sessionResumption',
+    },
+    'turnBehaviour.allowSteering': {
+        profileTypes: ['text', 'live'],
+        reason: 'image and speech turns take no mid-turn input',
+    },
+    'guardrails.quota': {
+        profileTypes: turnGuardrailTypes('quota'),
+        reason: 'quota counts model turns',
+    },
+    'guardrails.canary': {
+        profileTypes: ['text', 'image', 'live'],
+        reason: 'the canary is minted into a system prompt, which speech, decision and host profiles lack',
+        offValue: false,
+    },
+    'guardrails.promptEcho': {
+        profileTypes: ['text', 'image', 'live'],
+        reason: 'the echo is of a system prompt, which speech, decision and host profiles lack',
+        offValue: false,
+    },
+    'guardrails.sanitizeInput': {
+        profileTypes: turnGuardrailTypes('sanitizeInput'),
+        reason: 'the decision path runs none of the turn guardrails',
+    },
+    'guardrails.redactSensitive': {
+        profileTypes: turnGuardrailTypes('redactSensitive'),
+        reason: 'the decision path runs none of the turn guardrails',
+    },
+    'guardrails.egress': {
+        profileTypes: turnGuardrailTypes('egress'),
+        reason: 'egress gates user-visible model text in the turn runner',
+    },
+    'guardrails.network': {
+        profileTypes: turnGuardrailTypes('network'),
+        reason: 'the decision path calls no tools',
+    },
+    'guardrails.taint': {
+        profileTypes: turnGuardrailTypes('taint'),
+        reason: 'the decision path calls no tools',
+    },
+    'guardrails.disclosure': {
+        profileTypes: ['decision'],
+        reason: 'disclosure gates state leaving a decision profile for its model',
+    },
+};
+/**
+ * The scope entry that governs `path`: its own, else its nearest ancestor's.
+ * `undefined` means every profile type.
+ */
+export function profileFieldScope(path) {
+    const segments = path.split('.');
+    for (let end = segments.length; end > 0; end--) {
+        const scope = PROFILE_FIELD_SCOPE[segments.slice(0, end).join('.')];
+        if (scope)
+            return scope;
+    }
+    return undefined;
+}
+export function profileTypesForField(path) {
+    return profileFieldScope(path)?.profileTypes ?? ALL_PROFILE_TYPES;
+}
+/** Every set value under `segments`, keyed by concrete path; `*` walks each key of a map. */
+function valuesAt(root, segments, at = '') {
+    if (!segments.length)
+        return root === undefined ? [] : [[at, root]];
+    if (root === null || typeof root !== 'object')
+        return [];
+    const [head, ...rest] = segments;
+    const record = root;
+    const keys = head === '*' ? Object.keys(record) : [head];
+    return keys.flatMap((key) => valuesAt(record[key], rest, at ? `${at}.${key}` : key));
+}
+/**
+ * Every field `profile` sets that its type may not, ancestors before their
+ * children. A scope's off value is not reported.
+ */
+export function outOfScopeFields(profile) {
+    const out = [];
+    for (const [path, scope] of Object.entries(PROFILE_FIELD_SCOPE)) {
+        if (scope.profileTypes.includes(profile.type))
+            continue;
+        for (const [at, value] of valuesAt(profile, path.split('.'))) {
+            if (scope.offValue !== undefined && value === scope.offValue)
+                continue;
+            out.push({ path: at, scope });
+        }
+    }
+    return out;
+}

package/esm/src/kernel/registry/attachments.d.ts

@@ -0,0 +1,35 @@
+import { type ErrorCopy, TheoremError } from '../../guardrails/error.js';
+import { type LexiconOverrides } from '../../guardrails/lexicon.js';
+import type { AttachmentValidationIssue, MediaLimits, MimeInputs, Profile, TurnBlob, TurnMediaRef } from '../types.js';
+declare function resolveMediaLimits(inputs: MimeInputs): MediaLimits | undefined;
+/** A MIME-specific cap, then its category wildcard, then the global cap. */
+declare function maxBytesForMime(mimeType: string, limits: MediaLimits): number;
+declare function isTurnMediaRef(item: TurnBlob | TurnMediaRef): item is TurnMediaRef;
+declare function requireMediaLimits(profile: Profile): MediaLimits;
+/** CSV formula injection: formula-like cells get an apostrophe before they reach a model. */
+declare function sanitizeCsvText(text: string): string;
+/** `sizeBytes` is absent for provider references, which carry no bytes. */
+export interface AttachmentFacts {
+    name?: string;
+    mimeType: string;
+    sizeBytes?: number;
+}
+/** An absent `accept` list means the channel takes nothing. */
+export interface AttachmentRules {
+    attachments?: string[];
+    voice?: string[];
+    limits?: MediaLimits;
+}
+/** The one attachment check: the kernel throws on it at ingress and the headless interface runs it before a send. */
+declare function attachmentIssues(rules: AttachmentRules, files: AttachmentFacts[], clips: AttachmentFacts[]): AttachmentValidationIssue[];
+declare function attachmentIssueCopy(issue: AttachmentValidationIssue): ErrorCopy;
+declare function attachmentIssueText(issue: AttachmentValidationIssue, lexicon?: LexiconOverrides): string;
+declare function attachmentsRefused(issues: readonly AttachmentValidationIssue[]): TheoremError;
+/** Provider references are checked for MIME and count; byte limits apply to inline blobs only. */
+declare function assertTurnAttachments(profile: Profile, attachments: Array<TurnBlob | TurnMediaRef> | undefined, voice: TurnBlob[] | undefined): void;
+/** Provider file references pass through unsanitized: the kernel has no bytes to scan. */
+declare function sanitizeTurnBlobs(profile: Profile, attachments: Array<TurnBlob | TurnMediaRef> | undefined, voice: TurnBlob[] | undefined): {
+    attachments?: Array<TurnBlob | TurnMediaRef>;
+    voice?: TurnBlob[];
+};
+export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, };