@terminals-tech/sdk 1.0.0-rc.2 → 1.0.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { JSONSchema7 } from 'json-schema';
+import { Observable } from 'rxjs';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 
@@ -557,6 +558,9 @@ interface CoherenceMetrics$1 {
  * - Grounding: Connection to factual/contextual reality
  * - Internal: Self-consistency of reasoning
  * - Crystallization: Clarity and actionability of output
+ *
+ * Heuristic primitives are composed from L1 (core/primitives/coherence-heuristics).
+ * This module adds weights, configuration, explanations, and audio mapping.
  */
 
 type CoherenceMetrics = CoherenceMetrics$1;
@@ -923,7 +927,7 @@ declare function createDAG<N, E = void>(nodes: DAGNode<N>[], edges: DAGEdge<E>[]
  * @module sdk-types
  */
 
-interface NodePolicy$1 {
+interface NodePolicy {
     fs?: {
         mode?: "sandboxed" | "full";
         allowedPaths?: string[];
@@ -933,7 +937,7 @@ interface NodePolicy$1 {
         allowList?: string[];
     };
 }
-interface StackPolicies$1 {
+interface StackPolicies {
     fs?: {
         mode?: "sandboxed" | "full";
         allowedPaths?: string[];
@@ -2556,8 +2560,91 @@ declare namespace protocol {
   export { type protocol_AgentBus as AgentBus, type protocol_AgentMessage as AgentMessage, type protocol_AgentMessageType as AgentMessageType, type protocol_DelegationChain as DelegationChain, type protocol_DelegationEdge as DelegationEdge, type protocol_DelegationEdgeInput as DelegationEdgeInput, type protocol_DelegationEndpoint as DelegationEndpoint, protocol_createAgentBus as createAgentBus, protocol_createDelegationChain as createDelegationChain, protocol_createDelegationEdge as createDelegationEdge, protocol_isValidSurfaceId as isValidSurfaceId };
 }
 
-type NodePolicy = NodePolicy$1;
-type StackPolicies = StackPolicies$1;
+/**
+ * Trigger Type System
+ *
+ * Canonical discriminated-union types for all stack trigger mechanisms.
+ * A trigger defines *when* and *how* a stack run is initiated.
+ *
+ * Usage:
+ *   - StackManifestV0.triggerConfig holds the declared trigger for a stack.
+ *   - TriggerContext is injected into every run so downstream nodes can inspect
+ *     how the execution was started.
+ *   - NodeSecretRef lets webhook triggers reference vault-backed HMAC keys
+ *     through the provider control plane instead of inline secrets.
+ *
+ * @module machines/core/types/trigger
+ */
+
+/** Run the stack on a fixed time interval. */
+interface IntervalTriggerConfig {
+    kind: "interval";
+    /** Seconds between runs. Minimum enforced at 1. */
+    everySeconds: number;
+}
+/**
+ * Run the stack on a standard 5-field cron schedule.
+ *
+ * The expression follows the POSIX/Vixie-cron syntax:
+ *   `minute hour day-of-month month day-of-week`
+ *
+ * @example "0 9 * * 1-5"   // weekdays at 09:00 UTC
+ * @example "* /15 * * * *" // every 15 minutes (non-standard extended form)
+ */
+interface CronTriggerConfig {
+    kind: "cron";
+    /** Standard 5-field cron expression. */
+    expression: string;
+    /** IANA timezone name (default: "UTC"). */
+    timezone?: string;
+}
+/**
+ * Run the stack when an inbound HTTP webhook is received.
+ *
+ * Secret verification:
+ *   - Use `secretRef` for production — the key stays server-side.
+ *   - Use the inline `secret` field only for dev/test environments.
+ */
+interface WebhookTriggerConfig {
+    kind: "webhook";
+    /** Relative path segment appended to the stack webhook base URL. */
+    path?: string;
+    /** Accepted HTTP method (default: "POST"). */
+    method?: "GET" | "POST" | "PUT" | "PATCH";
+    /**
+     * Inline HMAC signing secret.
+     * Production deployments should prefer `secretRef` to keep the value
+     * server-side in the Supabase vault.
+     */
+    secret?: string;
+    /** Vault-backed secret reference for the HMAC signing key. */
+    secretRef?: NodeSecretRef;
+}
+/**
+ * Run the stack when a matching AXON event is published on the given topic.
+ *
+ * AXON cross-layer events are published via `system.signal.emit.v1` nodes or
+ * directly through the AXON kernel. The filter is applied against the event
+ * payload before dispatching.
+ */
+interface EventTriggerConfig {
+    kind: "event";
+    /** AXON event topic string (e.g. "brain.index.complete", "user.action.*"). */
+    topic: string;
+    /**
+     * Optional shallow equality filter applied to the event payload.
+     * Only events whose payload contains all key-value pairs in this map
+     * will dispatch the stack run.
+     */
+    filter?: Record<string, unknown>;
+}
+/** Run the stack only when explicitly requested via the API or UI. */
+interface ManualTriggerConfig {
+    kind: "manual";
+}
+/** Discriminated union over all trigger kinds. */
+type TriggerConfig = IntervalTriggerConfig | CronTriggerConfig | WebhookTriggerConfig | EventTriggerConfig | ManualTriggerConfig;
+
 /**
  * Runtime tier for node execution.
  *
@@ -2573,6 +2660,29 @@ type StackPolicies = StackPolicies$1;
  * const tier: RuntimeTier = "worker";
  */
 type RuntimeTier = "worker" | "container-lite" | "webcontainer" | "edge" | "wasm-hvm" | "stack";
+/**
+ * Secret reference for node execution.
+ *
+ * Links a secret from the vault into node environment.
+ *
+ * @example
+ * const secret: NodeSecretRef = {
+ *   name: "api_key",
+ *   scope: "stack",
+ *   env: "OPENAI_API_KEY",
+ *   required: true
+ * };
+ */
+interface NodeSecretRef {
+    /** Secret identifier in vault */
+    name: string;
+    /** Resolution scope: node-local or stack-wide */
+    scope: "node" | "stack";
+    /** Environment variable name (defaults to name if omitted) */
+    env?: string;
+    /** Whether secret must exist (default: false) */
+    required?: boolean;
+}
 /**
  * Base manifest fields shared by nodes and stacks.
  *
@@ -2628,6 +2738,24 @@ interface StackRuntimes {
     /** Per-node runtime tier overrides (nodeId -> tiers) */
     overrides?: Record<string, RuntimeTier[]>;
 }
+/**
+ * Reference from a stack node to a brain connector instance.
+ *
+ * Binds the connector's extracted data chunks into this node's input,
+ * allowing RAG / knowledge-graph results to flow into the execution graph.
+ */
+interface ConnectorRef {
+    /** ID of the ConnectorInstance in the brain pipeline. */
+    connectorId: string;
+    /** ID of the ConnectorDefinition (catalog entry). */
+    definitionId: string;
+    /**
+     * Optional shallow filter applied to DataChunks from this connector.
+     * Only chunks whose metadata contains all key-value pairs in this map
+     * will be included.
+     */
+    dataChunkFilter?: Record<string, unknown>;
+}
 /**
  * Node configuration within a stack.
  *
@@ -2655,6 +2783,11 @@ interface StackNodeConfig {
     policies?: NodePolicy;
     /** Secret names from stack.secrets */
     secrets?: string[];
+    /**
+     * Reference to a brain connector whose data chunks feed this node.
+     * The orchestrator resolves this at run-time before invoking the node.
+     */
+    connectorRef?: ConnectorRef;
 }
 /**
  * Directed edge connecting two nodes in the stack DAG.
@@ -2715,6 +2848,14 @@ interface StackManifestV0 extends BaseManifestV0 {
     runtimes?: StackRuntimes;
     /** Provenance layer (L0 or L1) */
     layer?: ManifestLayer;
+    /**
+     * Declared trigger for this stack.
+     *
+     * Defines when and how the stack is automatically started.
+     * The orchestrator and scheduler use this at registration time.
+     * When absent, the stack is manual-only.
+     */
+    triggerConfig?: TriggerConfig;
 }
 
 /**
@@ -3024,6 +3165,171 @@ declare namespace skill {
   export { skill_SKILL_CATEGORIES as SKILL_CATEGORIES, skill_SKILL_RANKS as SKILL_RANKS, skill_SKILL_RUN_STATUSES as SKILL_RUN_STATUSES, skill_SKILL_SIGNAL_CODES as SKILL_SIGNAL_CODES, skill_SKILL_TIERS as SKILL_TIERS, type skill_SkillAgent as SkillAgent, type skill_SkillCapabilities as SkillCapabilities, type skill_SkillCategory as SkillCategory, type skill_SkillEventType as SkillEventType, type skill_SkillHealth as SkillHealth, type skill_SkillManifest as SkillManifest, type skill_SkillMeta as SkillMeta, type skill_SkillRank as SkillRank, type skill_SkillRunStatus as SkillRunStatus, type skill_SkillSignalCode as SkillSignalCode, type skill_SkillTier as SkillTier, skill_ensureSkillsRegistered as ensureSkillsRegistered, skill_getAllSkills as getAllSkills, skill_getSkill as getSkill, skill_getSkillCount as getSkillCount, skill_getSkillsByCategory as getSkillsByCategory, skill_registerSkill as registerSkill };
 }
 
+/**
+ * Manifold Annihilation API
+ *
+ * Converges an Intent Manifold and a Context Manifold via py2bend compilation
+ * and HVM reduction where available.
+ */
+
+interface AnnihilationOptions {
+    maxSteps?: number;
+    convergenceThreshold?: number;
+    gravity?: number;
+}
+interface ManifoldReductionMetrics {
+    compiled: boolean;
+    reduced: boolean;
+    strategy: string;
+    runtime: "wasm-hvm" | "compile-only";
+    durationMs: number;
+    warnings: string[];
+    errors: string[];
+    logitBias: Record<string, number>;
+}
+interface ManifoldSematonPayload {
+    result: string;
+    steps: number;
+    intent: string;
+    contextSnapshot: string;
+    bendCode?: string;
+    reduction: ManifoldReductionMetrics;
+}
+declare function annihilate(intent: string, context?: string, options?: AnnihilationOptions): Promise<Sematon<ManifoldSematonPayload>>;
+declare const manifold: {
+    annihilate: typeof annihilate;
+};
+
+type manifold$1_AnnihilationOptions = AnnihilationOptions;
+type manifold$1_ManifoldReductionMetrics = ManifoldReductionMetrics;
+type manifold$1_ManifoldSematonPayload = ManifoldSematonPayload;
+declare const manifold$1_annihilate: typeof annihilate;
+declare const manifold$1_manifold: typeof manifold;
+declare namespace manifold$1 {
+  export { type manifold$1_AnnihilationOptions as AnnihilationOptions, type manifold$1_ManifoldReductionMetrics as ManifoldReductionMetrics, type manifold$1_ManifoldSematonPayload as ManifoldSematonPayload, manifold$1_annihilate as annihilate, manifold$1_manifold as manifold };
+}
+
+/**
+ * StateMirror - Total Context Encoding
+ *
+ * Continuously encodes the entire application, UI, and cognitive state into a
+ * shared representational manifold. This provides the ObserverKernel with literal
+ * environmental awareness, preventing "blind" execution.
+ */
+
+interface SystemStateSnapshot {
+    /** The current URL or deep-link active in the browser */
+    activeUrl: string;
+    /** The specific UI component currently focused or under cursor */
+    focusedComponent: string | null;
+    /** The last N intents expressed by the user */
+    recentIntents: string[];
+    /** Latest L1 AudioKernel spectral entropy [0,1] */
+    audioEntropy: number;
+    /** Whether the NanoFold 3D surface is actively rendering */
+    nanoFoldActive: boolean;
+    /** Current System Coherence R [0,1] */
+    coherenceR: number;
+    /** Current active project or workspace ID */
+    activeProject: string | null;
+}
+declare class StateMirror {
+    private state$;
+    private bridgeOwnerId;
+    private bridgeOrder;
+    constructor();
+    private initSubscriptions;
+    /** Gets the observable stream of state changes */
+    get stream$(): Observable<SystemStateSnapshot>;
+    /** Gets a synchronous snapshot of the current state */
+    get snapshot(): SystemStateSnapshot;
+    claimBridge(bridgeId: string): void;
+    releaseBridge(bridgeId: string): void;
+    /** Partially updates the mirror state */
+    update(partial: Partial<SystemStateSnapshot>): void;
+    /**
+     * Bridge-scoped update to prevent multiple mounted app shells from racing
+     * against the same singleton mirror.
+     */
+    updateFromBridge(bridgeId: string, partial: Partial<SystemStateSnapshot>): void;
+    /**
+     * Flattens the continuous state into a dense text manifold.
+     * This is passed to the ObserverKernel to ground it in the immediate UI/UX reality.
+     */
+    encodeToManifold(): string;
+}
+
+/**
+ * ObserverField & Neurons
+ *
+ * Formalization of the Terminals abstraction:
+ * The MicroLM is not a calculator. It is a continuous ObserverKernel.
+ * Skills are not apps. They are geometric Neurons equipped by the Observer.
+ *
+ * @module sdk/observer
+ */
+
+/**
+ * A hot-swappable structural template that the Observer equips to resolve intent.
+ */
+interface Neuron {
+    id: string;
+    kind: "skill" | "isomorphism" | "prompt-sensor" | "py2bend-template";
+    payload: unknown;
+    gravity: number;
+}
+interface ObserverConfig {
+    id: string;
+    heartbeatHz?: number;
+    stateMirror?: StateMirror;
+}
+/**
+ * ObserverKernel - Continuous Local Witness
+ *
+ * An active, unbroken presence that maintains a heartbeat,
+ * observes the StateMirror, and equips Neurons (skills) dynamically.
+ */
+declare class ObserverKernel {
+    readonly id: string;
+    readonly heartbeatHz: number;
+    private mirror;
+    private activeNeurons;
+    private coherenceR$;
+    private pulseTimer;
+    constructor(config: ObserverConfig);
+    get coherence(): number;
+    get isRunning(): boolean;
+    /** Starts the continuous heartbeat */
+    start(): void;
+    /** Stops the heartbeat */
+    stop(): void;
+    /** The continuous observation loop */
+    private pulse;
+    /** Equips a new geometric constraint (Neuron) onto the observer */
+    equipNeuron(neuron: Neuron): void;
+    /** Unequips a Neuron */
+    unequipNeuron(neuronId: string): void;
+    /** Replace the active neuron field in one operation. */
+    syncNeurons(neurons: Neuron[]): void;
+    /**
+     * The core execution path:
+     * Flattens the active Neurons + StateMirror context, then drops them into the Annihilator.
+     */
+    resolve(intent: string): Promise<Sematon<any>>;
+}
+declare function disposeObserverKernel(id: string): void;
+declare function getObserverKernel(id: string, config?: Omit<ObserverConfig, "id">): ObserverKernel;
+
+type observer_Neuron = Neuron;
+type observer_ObserverConfig = ObserverConfig;
+type observer_ObserverKernel = ObserverKernel;
+declare const observer_ObserverKernel: typeof ObserverKernel;
+declare const observer_disposeObserverKernel: typeof disposeObserverKernel;
+declare const observer_getObserverKernel: typeof getObserverKernel;
+declare namespace observer {
+  export { type observer_Neuron as Neuron, type observer_ObserverConfig as ObserverConfig, observer_ObserverKernel as ObserverKernel, observer_disposeObserverKernel as disposeObserverKernel, observer_getObserverKernel as getObserverKernel };
+}
+
 /**
  * MCP Sampling Support (MCP Specification 2025-11-25)
  *
@@ -3503,6 +3809,6 @@ declare function createAxonBus(): InMemoryAxonBus;
  *
  * Curated package facade for the npm package.
  */
-declare const SDK_VERSION = "1.0.0-rc.1";
+declare const SDK_VERSION = "1.0.0";
 
-export { type AxonMessage, type AxonMessageBus, brain as Brain, core as Core, InMemoryAxonBus, index as L0, mesh as Mesh, protocol as Protocol, ProtocolBridge, SDK_VERSION, skill as Skill, terminal as Terminal, createAxonBus, createProtocolBridge };
+export { type AxonMessage, type AxonMessageBus, brain as Brain, core as Core, InMemoryAxonBus, index as L0, manifold$1 as Manifold, mesh as Mesh, observer as Observer, protocol as Protocol, ProtocolBridge, SDK_VERSION, skill as Skill, terminal as Terminal, createAxonBus, createProtocolBridge };