@theoremjs/studio 0.0.0-stage → 0.3.2

package/deno.json

@@ -0,0 +1,3 @@
+{
+  "nodeModulesDir": "manual"
+}

package/draft.d.ts

@@ -0,0 +1,407 @@
+/**
+ * Every section is always present so switching profile type keeps what the author typed.
+ * "Provider default" numbers are `null` and booleans hold the value the kernel would resolve,
+ * so compile emits a field only when it differs.
+ */
+import { type LabelKey } from '@theoremjs/agents';
+import { type BlockedReplyOnBlock, type Boundary, type DestinationGate, type DetectAction, type Detector, type TaintGate, type UrlDetector } from '@theoremjs/agents/guardrails';
+import { type JsonObject, type ProfileItemRule } from '@theoremjs/agents/kernel';
+import { type CompactionMeter, type CompactionTiming, type ContextSender, type ContinueStopKind, type KeySlot, type LiveActivityHandling, type LiveEndSensitivity, type LiveStartSensitivity, type ProfileGraphFacetId, type ProfileType, type SpeechAudioFormat, type StepLimitMode, type StreamMode, type ThinkingLevel } from '@theoremjs/agents/schema';
+import type { ModelPicks, ModelStart } from './lent-keys.ts';
+import { type StudioProvider } from './providers.ts';
+import type { StudioToolSpecSeed } from './types.ts';
+export type StudioProfileType = ProfileType;
+/** The types that run a model turn; a decision asks questions, and a host runs its tools. */
+export type StudioTurnProfileType = Exclude<StudioProfileType, 'decision' | 'host'>;
+export declare const STUDIO_PROFILE_TYPES: readonly StudioProfileType[];
+export interface IdentityDraft {
+    agentId: string;
+    profileType: StudioProfileType | '';
+    handle: string;
+    /** Private sections are wrapped as `{private: …}`. Unused on speech, which has no system channel. */
+    system: string;
+    /** Other instructions by the role a turn names, as a JSON object of strings (with `{private: …}` sections) or parts; blank omits it. */
+    systemByRoleJson: string;
+}
+export interface ModelsDraft {
+    /** Who holds the conversation a saved state continues; unset is the kernel's default, the host. */
+    providerHistory?: 'host' | 'stateless' | 'provider';
+    defaultModel: string;
+    allowModelSelect: boolean;
+    /** `null` omits it: the kernel's default cap applies. */
+    maxSteps: number | null;
+    /** The vault slot every model uses unless it names its own. */
+    key: KeySlot | '';
+    /** The slot a quota refusal retries on once; `''` or absent names none. */
+    fallbackKey?: KeySlot | '';
+}
+export interface EffortDraft {
+    alias: string;
+    level: ThinkingLevel;
+}
+export interface ModelBindingDraft {
+    /** Stable draft key; the model id is editable, so it cannot be the key. */
+    key: string;
+    modelId: string;
+    /** The API shape it is spoken to in, by the id of a protocol its provider serves. */
+    protocol: string;
+    /** The provider that serves it, by the id one of the draft's `providers` has. */
+    provider: string;
+    apiId: string;
+    /** What its protocol takes beyond the shared settings, as the protocol's own schema reads them. */
+    options: JsonObject;
+    /** Decision request timeout; `null` uses the studio timeout. */
+    timeoutMs: number | null;
+    efforts: EffortDraft[];
+    defaultEffort: string;
+    allowEffortSelect: boolean;
+    /** Thought summaries: on, off, or `null` to leave it to the provider. */
+    summaries: boolean | null;
+    maxOutputTokens: number | null;
+    temperature: number | null;
+    builtInTools: string[];
+    /** This model's own vault slot; `''` or absent uses the profile's. */
+    keySlot?: KeySlot | '';
+    /** This model's own fallback slot; `''` or absent uses the profile's. */
+    fallbackKeySlot?: KeySlot | '';
+    /** When the agent compacts its own history; `''` or absent leaves compaction off. Text only. */
+    compactTiming?: CompactionTiming | '';
+    /** The token budget `compactAt` is a fraction of. */
+    compactMaxTokens?: number | null;
+    /** The fraction of the budget, between 0 and 1, at which compaction starts. */
+    compactAt?: number;
+    /** Recent history kept word for word: exchanges, a fraction of the budget, or 0 for none. */
+    compactKeep?: number | null;
+    /** What counts toward the budget; `''` or absent is history. */
+    compactMeter?: CompactionMeter | '';
+    /** The workspace agent that writes the summary, by key; `''` or absent: this agent. */
+    compactWith?: string;
+}
+/** Where compaction starts when a builder turns it on; every number stays theirs to change. */
+export declare const COMPACTION_DRAFT_DEFAULTS: {
+    readonly compactMaxTokens: 32000;
+    readonly compactAt: 0.75;
+    readonly compactKeep: 4;
+};
+export interface ToolsDraft {
+    /** Function tool that promotes T2 tools; empty omits it. */
+    t2Loader: string;
+    /** True: a step's calls run side by side. False omits it: one at a time. */
+    parallel: boolean;
+}
+/** One custom tool: compiles to `registerTool` plus a `tools.allow` entry. */
+export interface ToolSpecDraft extends StudioToolSpecSeed {
+    key: string;
+}
+export interface InputsDraft {
+    text: boolean;
+    attachmentsAccept: string[];
+    voiceAccept: string[];
+    maxFiles: number | null;
+    maxBytes: number | null;
+    maxTurnBytes: number | null;
+    /** Size limits by file type, as a JSON object of byte counts; blank omits it. */
+    limitsByMimeJson: string;
+    /** Named choices a turn can make, as a JSON object of value lists; blank omits it. */
+    slotsJson: string;
+    /** Who may send the agent context; none omits `inputs.context`. */
+    contextFrom: ContextSender[];
+    /** The longest context package from each sender, in characters of JSON. */
+    contextMaxChars: number | null;
+}
+export interface OutputsDraft {
+    mode: 'text' | 'structured';
+    schemaId: string;
+    schemaJson: string;
+    /** `''` omits it (kernel default: SSE). */
+    streamMode: '' | StreamMode;
+    streamThoughts: boolean;
+    validationEnabled: boolean;
+    maxRetries: number | null;
+    /** What a refused item of a list does, by the list's path. The check on the item is code. */
+    itemRules: Record<string, ItemRuleOnFail>;
+    repairGuidance: string;
+}
+export type ItemRuleOnFail = ProfileItemRule['onFail'];
+export interface TurnBehaviourDraft {
+    resumeEnabled: boolean;
+    allowContinue: ContinueStopKind[];
+    autoContinue: ContinueStopKind[];
+    maxContinues: number | null;
+    continueInstruction: string;
+    allowSteering: boolean;
+    atStepLimit: StepLimitMode;
+}
+/** What a URL detector lets through besides the URLs the model was given. */
+export interface UrlAllowDraft {
+    hosts: string[];
+    fromTools: boolean;
+}
+/** One pattern of the builder's own: a regular expression, or words matched whole. */
+export interface PatternDraft {
+    name: string;
+    kind: 'pattern' | 'words';
+    /** The regular expression's source, while `kind` is `pattern`. */
+    pattern: string;
+    /** Its flags, from `i`, `m`, `s`, and `u`. */
+    flags: string;
+    /** The words, while `kind` is `words`. */
+    words: string[];
+}
+/** Whose patterns a detector reads with: Theorem's, the builder's, both, or neither. */
+export interface PatternSourceDraft {
+    theorem: boolean;
+    patterns: PatternDraft[];
+    /** What a retry tells the model about a match of the builder's patterns. `''` keeps the labels'. */
+    hint: string;
+}
+/** A detector of the builder's own, read with its patterns. */
+export interface OwnDetectorDraft {
+    /** `namespace.name`. */
+    key: string;
+    label: string;
+    /** What it does with a match, at every boundary. */
+    at: Record<Boundary, DetectAction>;
+    patterns: PatternDraft[];
+    /** What a retry tells the model about a match. `''` keeps the labels'. */
+    hint: string;
+}
+export interface GuardrailsDraft {
+    /** The note that binds the canary, while `canary_leak` reads somewhere. */
+    canaryBindNote: string;
+    /** What each detector does with a match, at every boundary. */
+    detect: Record<Detector, Record<Boundary, DetectAction>>;
+    /** Whose patterns each detector that reads with patterns uses, by detector. */
+    sources: Record<string, PatternSourceDraft>;
+    /** Detectors of the builder's own. */
+    own: OwnDetectorDraft[];
+    quotaEnabled: boolean;
+    quotaPerDay: number | null;
+    quotaMessage: string;
+    /** What `ungiven_images` and `ungiven_links` let through. */
+    allow: Record<UrlDetector, UrlAllowDraft>;
+    /** The names of tools and parameters `tool_leak` lets through. */
+    innocentNames: string[];
+    /** `''` omits it (kernel default: retry). */
+    blockedReplyOnBlock: BlockedReplyOnBlock | '';
+    /** `null` omits it (kernel default: 1). */
+    blockedReplyMaxRetries: number | null;
+    egressRepairGuidance: string;
+    /** What the user reads in place of a refused reply. `''` keeps the labels'. */
+    egressRefusal: string;
+    allowPrivateNetworks: boolean;
+    allowedHosts: string[];
+    /** Empty omits it: https, plus http with private networks. */
+    allowedSchemes: string[];
+    /** `''` omits it (kernel default: off). */
+    taintAfterRemoteRead: TaintGate | '';
+    /** `''` omits it (kernel default: off). */
+    taintRemoteDestination: DestinationGate | '';
+}
+export interface ObservabilityDraft {
+    /** The store traces go to, or `false` when they are off. */
+    writeTo: false | string;
+    /** The store they go to when they are on: the studio's, or the one a project's profile names. */
+    destination: string;
+    sampleRate: number;
+    include: {
+        upstreamLog: boolean;
+        outboundWire: boolean;
+        evidenceRaw: boolean;
+        usage: boolean;
+        guardrailDecisions: boolean;
+        guardrailMatchPreview: boolean;
+    };
+    scrub: {
+        sensitive: boolean;
+        injection: boolean;
+        canary: boolean;
+    };
+    retainForDays: number | null;
+    rotateAfterMiB: number | null;
+    /** Attributes on every trace, as a JSON object; blank omits it. */
+    resourceJson: string;
+}
+/** A pinned reference image: a file's bytes, or a link to one. */
+export type ImageReferenceDraft = {
+    key: string;
+    name: string;
+    mimeType: string;
+    data: string;
+} | {
+    key: string;
+    uri: string;
+    name?: string;
+};
+export interface ImageDraft {
+    aspectRatio: string;
+    resolution: string;
+    mimeType: string;
+    /** Provider vocabularies (OpenRouter: auto, low, medium, high); blank is the provider default. */
+    quality: string;
+    /** Provider vocabularies (OpenRouter: auto, transparent, opaque); blank is the provider default. */
+    background: string;
+    n: number | null;
+    seed: number | null;
+    outputCompression: number | null;
+    includeText: boolean;
+    references: ImageReferenceDraft[];
+}
+export interface SpeechDraft {
+    voice: string;
+    /** How the script is delivered; blank gives no direction. */
+    style: string;
+    /** The speaking rate; `null` keeps the voice's own pace. */
+    speed: number | null;
+    format: '' | SpeechAudioFormat;
+}
+export interface LiveDraft {
+    ingressAudio: boolean;
+    ingressVideo: boolean;
+    ingressText: boolean;
+    voice: string;
+    sessionResumption: boolean;
+    /** The prompt a new call opens with, so the agent speaks first; blank omits it. */
+    greeting: string;
+    /** The prompt a resumed call opens with; blank omits `live.resumed`. */
+    resumedPrompt: string;
+    resumedAfterMs: number | null;
+    /** Context window compression by sliding window; the two numbers are its trigger and target. */
+    contextCompression: boolean;
+    compressionTriggerTokens: number | null;
+    compressionTargetTokens: number | null;
+    transcriptionInput: boolean;
+    transcriptionOutput: boolean;
+    vadActivityHandling: '' | LiveActivityHandling;
+    vadStartSensitivity: '' | LiveStartSensitivity;
+    vadEndSensitivity: '' | LiveEndSensitivity;
+    vadPrefixPaddingMs: number | null;
+    vadSilenceDurationMs: number | null;
+}
+export type DecisionQuestionType = 'choice' | 'score' | 'noul' | 'box';
+/** A choice's option or a number's named criterion (`label`), or a score's level (`text` only). */
+export interface DecisionCriterionDraft {
+    key: string;
+    label: string;
+    text: string;
+}
+export interface DecisionQuestionDraft {
+    key: string;
+    id: string;
+    type: DecisionQuestionType;
+    instructions: string;
+    /** A score's levels run from 0 at the top. */
+    criteria: DecisionCriterionDraft[] /** A box's image: one of the decision's images, such as `<ghs02>`, or a state field. Unset, the instructions say. */;
+    image?: string;
+}
+/** A picture every decision sends, which the questions write as its name in angle brackets. */
+export interface DecisionImageDraft {
+    key: string;
+    /** The reference without its brackets: `ghs02` is written `<ghs02>`. */
+    name: string;
+    mimeType: string;
+    data: string;
+}
+/** A decision profile and the questions it asks. The state they are asked about is typed where it runs, not saved. */
+export interface DecisionDraft {
+    contract: string;
+    /** `null` is the studio's most. */
+    maxStateBytes: number | null;
+    questions: DecisionQuestionDraft[];
+    images: DecisionImageDraft[];
+}
+/** Wording the author replaced, by labels key; a key left out keeps the kernel's line. */
+export type LabelsDraft = Partial<Record<LabelKey, string>>;
+/** Wording held beside the setting it words; each line has one value, so it edits that field. */
+export declare const INLINE_LABELS: Partial<Record<LabelKey, ProfileGraphFacetId>>;
+export interface StudioDraft {
+    identity: IdentityDraft;
+    /** Optional spine facets the author added (`PROFILE_GRAPH` rows with `optional`). */
+    included: ProfileGraphFacetId[];
+    models: ModelsDraft;
+    modelBindings: ModelBindingDraft[];
+    /** The providers its models pick from: the workspace's. */
+    providers: StudioProvider[];
+    tools: ToolsDraft;
+    toolSpecs: ToolSpecDraft[];
+    inputs: InputsDraft;
+    outputs: OutputsDraft;
+    turnBehaviour: TurnBehaviourDraft;
+    guardrails: GuardrailsDraft;
+    observability: ObservabilityDraft;
+    image: ImageDraft;
+    speech: SpeechDraft;
+    live: LiveDraft;
+    decision: DecisionDraft;
+    labels: LabelsDraft;
+}
+export declare function draftKey(prefix: 'agent' | 'model' | 'tool' | 'question' | 'criterion' | 'reference' | 'image'): string;
+export declare function defaultModelBinding(partial?: Partial<ModelBindingDraft>): ModelBindingDraft;
+export declare function defaultToolSpec(partial?: Partial<ToolSpecDraft>): ToolSpecDraft;
+/**
+ * The change that points an agent tool at an agent. A description that is
+ * still the new tool's stub, or empty, comes to say what the tool now does.
+ */
+export declare function agentToolTarget(tool: ToolSpecDraft, agentKey: string, agentId: string): Partial<ToolSpecDraft>;
+/** A pattern to fill in. */
+export declare function newPattern(): PatternDraft;
+/** A detector of the builder's own to fill in: it reads nowhere until a boundary is set. */
+export declare function newOwnDetector(): OwnDetectorDraft;
+/** A guardrail on a tool call the agent is about to make: whether to let it run, and how much is at stake. */
+export declare function exampleDecisionDraft(): DecisionDraft;
+/** State the example's questions can be asked about: the field a decision preview starts with. */
+export declare const EXAMPLE_DECISION_STATE: string;
+/** Span accepts a JSON string state; the preview starts with that shape for Span models. */
+export declare const EXAMPLE_SPAN_DECISION_STATE: string;
+/** Documents an embedding preview starts with, one per paragraph: a small help centre in a few topics, with a couple that belong to none. */
+export declare const EXAMPLE_EMBEDDING_TEXT: string;
+/** The question an embedding preview starts with, nearest the first document. */
+export declare const EXAMPLE_EMBEDDING_QUERY = "How do I delete every screenshot on my desktop?";
+/** A new question of `type`, with an id the draft doesn't use yet. */
+export declare function newDecisionQuestion(draft: StudioDraft, type?: DecisionQuestionType): DecisionQuestionDraft;
+/**
+ * A picture added from `file`, named after it in the way a reference is written: lowercase, with
+ * `_` for anything else, and `_2`, `_3` after a name the draft has.
+ */
+export declare function newDecisionImage(draft: StudioDraft, file: string, image: {
+    mimeType: string;
+    data: string;
+}): DecisionImageDraft;
+/** The rows a question of `type` starts with: two options, two levels, or none. */
+export declare function newCriteria(type: DecisionQuestionType): DecisionCriterionDraft[];
+/**
+ * An empty draft: no profile type chosen, every section at its kernel default
+ * except observability, which the studio includes and points at its own
+ * trace destination.
+ */
+export declare function createBlankDraft(): StudioDraft;
+/** Required facets for the type plus the included optional ones, in catalog order. */
+export declare function draftFacets(draft: StudioDraft): ProfileGraphFacetId[];
+/** By the kernel's `PROFILE_FIELD_SCOPE`; false until a type is chosen. */
+export declare function draftAllows(draft: StudioDraft, path: string): boolean;
+/** A canary is bound into a system prompt while `canary_leak` reads somewhere. */
+export declare function plantsCanary(draft: StudioDraft): boolean;
+export declare function takesContinueInstruction(draft: StudioDraft): boolean;
+export declare function includableFacets(draft: StudioDraft): ProfileGraphFacetId[];
+/** Updates a binding and keeps the default model attached to it through an id change. */
+export declare function updateModelBinding(draft: StudioDraft, bindingKey: string, change: Partial<ModelBindingDraft>): StudioDraft;
+/**
+ * Drops a binding, and the default model with it when it was that one. Model select turns off
+ * below two bindings, as on a type switch.
+ */
+export declare function removeModelBinding(draft: StudioDraft, bindingKey: string): StudioDraft;
+/** A new model for the draft's type, starting where `start` puts it, or on no model yet. */
+export declare function newModelBinding(draft: StudioDraft, start?: ModelStart): ModelBindingDraft;
+export declare function newToolSpec(draft: StudioDraft): ToolSpecDraft;
+/** `first` if nothing has taken it, else the first `nth(2)`, `nth(3)`, … that is free. */
+export declare function freeName(first: string, taken: Iterable<string>, nth: (n: number) => string): string;
+/**
+ * Bindings whose model the kernel says can't serve the new type are dropped, and so are those
+ * `keys` list only for another type; if none remain, a new one starts where `keys` start one. Model select turns off below two bindings. Other sections and
+ * `included` are kept, so a facet the type lacks comes back when switching back. A host runs no
+ * model, so it keeps the bindings for the way back.
+ */
+export declare function setProfileType(draft: StudioDraft, type: StudioProfileType, keys?: ModelPicks): StudioDraft;
+export declare function includeFacet(draft: StudioDraft, id: ProfileGraphFacetId): StudioDraft;
+/** Its values stay on the draft for when it comes back. */
+export declare function excludeFacet(draft: StudioDraft, id: ProfileGraphFacetId): StudioDraft;