@almadar/agent 3.3.0 → 3.5.2

package/dist/agent/skill-agent.d.ts

@@ -12,6 +12,7 @@
  * independent of any specific skill registry location.
  */
 import { Command } from '@langchain/langgraph';
+import type { StructuredTool } from '@langchain/core/tools';
 import { type LLMProvider } from '@almadar/llm';
 import { type SubagentEventCallback, type OrbitalCompleteCallback, type DomainOrbitalCompleteCallback } from '../tools/index.js';
 import { SessionManager } from './session-manager.js';
@@ -99,6 +100,10 @@ export interface SkillAgentOptions {
     }>(tool: T) => T;
     /** Optional: Use orchestrated generation/fixing with complexity-based routing */
     useOrchestration?: boolean;
+    /** Optional: Additional tools to register alongside the built-in tools */
+    extraTools?: StructuredTool[];
+    /** Optional: When true, ONLY use extraTools (skip built-in execute, finishTask, etc.) */
+    extraToolsOnly?: boolean;
 }
 /**
  * Agent interface with stream method (simplified from DeepAgent)

package/dist/evals/utils/orbital-validate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Orbital CLI Validation Utility
+ *
+ * Shells out to `orbital validate --json <file>` for real schema validation.
+ * The CLI always exits 0 and outputs JSON with validation results.
+ *
+ * @packageDocumentation
+ */
+export interface OrbitalValidationError {
+    code: string;
+    path: string;
+    message: string;
+    suggestion?: string;
+}
+export interface OrbitalValidationStats {
+    orbitals: number;
+    entities: number;
+    traits: number;
+    pages: number;
+}
+export interface OrbitalValidationResult {
+    valid: boolean;
+    errors: OrbitalValidationError[];
+    stats?: OrbitalValidationStats;
+}
+/**
+ * Validate an orbital schema using the `orbital validate` CLI.
+ *
+ * @param schema - JSON schema object or JSON string
+ * @param workDir - Directory to write the temp .orb file
+ * @returns Validation result with errors and stats
+ */
+export declare function validateWithOrbitalCLI(schema: unknown, workDir: string): OrbitalValidationResult;

package/dist/gates/_debug.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+/**
+ * Debug script: full Gate 0 → 0.5 → 1 → 2 → 3 → 4 → verify chain on a single prompt.
+ *
+ * Usage:
+ *   export $(grep -E '^(DEEPSEEK|OPEN_ROUTER)' ../../.env | xargs)
+ *   npx tsx src/gates/_debug.ts                      # pure mode
+ *   npx tsx src/gates/_debug.ts --guided              # guided mode (LLM picks golden behavior)
+ *   npx tsx src/gates/_debug.ts --no-verify           # skip orbital-verify
+ *   npx tsx src/gates/_debug.ts --prompt "Todo app"   # custom prompt
+ */
+import 'dotenv/config';

package/dist/gates/agent-single-pass.d.ts

@@ -0,0 +1 @@
+import 'dotenv/config';

package/dist/gates/agentic/run.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env tsx
+/**
+ * Agentic Gates Runner
+ *
+ * Claude main agent with gate tools. Decomposes, matches behaviors,
+ * builds orbitals via gate pipeline, verifies, iterates on failures.
+ *
+ * Usage:
+ *   export $(grep -E '^(DEEPSEEK|OPEN_ROUTER|ANTHROPIC)' ../../.env | xargs)
+ *   npx tsx src/gates/agentic/run.ts
+ *   npx tsx src/gates/agentic/run.ts --prompt "Todo app with categories"
+ */
+import 'dotenv/config';

package/dist/gates/agentic/tools.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Agentic Gate Tools
+ *
+ * LangGraph-compatible tools that wrap the gate pipeline for use
+ * by a Claude main agent. Each tool is a scoped operation:
+ *
+ * - decompose_app: break prompt into orbital plan (Gate 0 subagent)
+ * - match_behavior: find golden behavior (Gate 0.5 subagent)
+ * - build_orbital: run gate pipeline on one orbital (Gates 1-4, DeepSeek)
+ * - verify_app: run orbital-verify (deterministic)
+ *
+ * The main agent (Claude) decides what to call, reads results, iterates.
+ * The gate subagents (DeepSeek) do the scoped generation.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+import type { OrbitalSchema } from '@almadar/core/types';
+export declare function createDecomposeAppTool(): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    prompt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+}, {
+    prompt: string;
+}>, {
+    prompt: string;
+}, {
+    prompt: string;
+}, {
+    appName: string;
+    orbitals: {
+        name: string;
+        entityName: string;
+        traitNames: string[];
+        pageCount: number;
+    }[];
+    shellOrb: OrbitalSchema;
+}, unknown, "decompose_app">;
+export declare function createMatchBehaviorTool(): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    description: z.ZodString;
+    orbitalName: z.ZodString;
+    entityName: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    orbitalName: string;
+    entityName: string;
+}, {
+    description: string;
+    orbitalName: string;
+    entityName: string;
+}>, {
+    description: string;
+    orbitalName: string;
+    entityName: string;
+}, {
+    description: string;
+    orbitalName: string;
+    entityName: string;
+}, {
+    matched: boolean;
+    behaviorName: string | null;
+    hasGoldenOrb: boolean;
+}, unknown, "match_behavior">;
+export declare function createBuildOrbitalTool(workDir: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    orbitalName: z.ZodString;
+    shellOrb: z.ZodString;
+    goldenBehavior: z.ZodOptional<z.ZodString>;
+    feedback: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    orbitalName: string;
+    shellOrb: string;
+    goldenBehavior?: string | undefined;
+    feedback?: string | undefined;
+}, {
+    orbitalName: string;
+    shellOrb: string;
+    goldenBehavior?: string | undefined;
+    feedback?: string | undefined;
+}>, {
+    orbitalName: string;
+    shellOrb: string;
+    goldenBehavior?: string | undefined;
+    feedback?: string | undefined;
+}, {
+    orbitalName: string;
+    shellOrb: string;
+    goldenBehavior?: string | undefined;
+    feedback?: string | undefined;
+}, {
+    success: boolean;
+    error: string;
+    orbitalName?: undefined;
+    orbitalsWritten?: undefined;
+    validation?: undefined;
+} | {
+    success: boolean;
+    orbitalName: string;
+    orbitalsWritten: number;
+    validation: {
+        valid: boolean;
+        errorCount: number;
+        errors: string[];
+    };
+    error?: undefined;
+} | {
+    success: boolean;
+    orbitalName: string;
+    error: string;
+    orbitalsWritten?: undefined;
+    validation?: undefined;
+}, unknown, "build_orbital">;
+export declare function createVerifyAppTool(workDir: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    orbPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    orbPath?: string | undefined;
+}, {
+    orbPath?: string | undefined;
+}>, {
+    orbPath?: string | undefined;
+}, {
+    orbPath?: string | undefined;
+}, {
+    success: boolean;
+    error: string;
+    passed?: undefined;
+    failed?: undefined;
+    total?: undefined;
+    coverage?: undefined;
+    failures?: undefined;
+} | {
+    success: boolean;
+    passed: number;
+    failed: number;
+    total: number;
+    coverage: number | null;
+    failures: string[];
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    passed: number;
+    failed: number;
+    total: number;
+    coverage: null;
+    failures: string[];
+}, unknown, "verify_app">;
+export declare function createUseBehaviorTool(workDir: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    behaviorName: z.ZodString;
+    entityName: z.ZodString;
+    fieldsJson: z.ZodString;
+    persistence: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    createButtonLabel: z.ZodOptional<z.ZodString>;
+    pageName: z.ZodOptional<z.ZodString>;
+    pagePath: z.ZodOptional<z.ZodString>;
+    isInitialPage: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    entityName: string;
+    behaviorName: string;
+    fieldsJson: string;
+    persistence?: string | undefined;
+    title?: string | undefined;
+    createButtonLabel?: string | undefined;
+    pageName?: string | undefined;
+    pagePath?: string | undefined;
+    isInitialPage?: boolean | undefined;
+}, {
+    entityName: string;
+    behaviorName: string;
+    fieldsJson: string;
+    persistence?: string | undefined;
+    title?: string | undefined;
+    createButtonLabel?: string | undefined;
+    pageName?: string | undefined;
+    pagePath?: string | undefined;
+    isInitialPage?: boolean | undefined;
+}>, {
+    entityName: string;
+    behaviorName: string;
+    fieldsJson: string;
+    persistence?: string | undefined;
+    title?: string | undefined;
+    createButtonLabel?: string | undefined;
+    pageName?: string | undefined;
+    pagePath?: string | undefined;
+    isInitialPage?: boolean | undefined;
+}, {
+    entityName: string;
+    behaviorName: string;
+    fieldsJson: string;
+    persistence?: string | undefined;
+    title?: string | undefined;
+    createButtonLabel?: string | undefined;
+    pageName?: string | undefined;
+    pagePath?: string | undefined;
+    isInitialPage?: boolean | undefined;
+}, {
+    success: boolean;
+    error: string;
+    behaviorName?: undefined;
+    entityName?: undefined;
+    orbitalPath?: undefined;
+    usedFunction?: undefined;
+    validation?: undefined;
+} | {
+    success: boolean;
+    behaviorName: string;
+    entityName: string;
+    orbitalPath: string;
+    usedFunction: boolean;
+    validation: {
+        valid: boolean;
+        errorCount: number;
+        errors: string[];
+    };
+    error?: undefined;
+}, unknown, "use_behavior">;
+export declare function createConnectTool(workDir: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    emitterFile: z.ZodString;
+    listenerFile: z.ZodString;
+    eventName: z.ZodString;
+    triggersEvent: z.ZodOptional<z.ZodString>;
+    payloadJson: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    emitterFile: string;
+    listenerFile: string;
+    eventName: string;
+    triggersEvent?: string | undefined;
+    payloadJson?: string | undefined;
+}, {
+    emitterFile: string;
+    listenerFile: string;
+    eventName: string;
+    triggersEvent?: string | undefined;
+    payloadJson?: string | undefined;
+}>, {
+    emitterFile: string;
+    listenerFile: string;
+    eventName: string;
+    triggersEvent?: string | undefined;
+    payloadJson?: string | undefined;
+}, {
+    emitterFile: string;
+    listenerFile: string;
+    eventName: string;
+    triggersEvent?: string | undefined;
+    payloadJson?: string | undefined;
+}, {
+    success: boolean;
+    error: string;
+    event?: undefined;
+    emitter?: undefined;
+    listener?: undefined;
+} | {
+    success: boolean;
+    event: string;
+    emitter: string;
+    listener: string;
+    error?: undefined;
+}, unknown, "connect_behaviors">;
+export declare function createComposeTool(workDir: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    appName: z.ZodOptional<z.ZodString>;
+    orbitalFiles: z.ZodOptional<z.ZodString>;
+    pagesJson: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    appName?: string | undefined;
+    orbitalFiles?: string | undefined;
+    pagesJson?: string | undefined;
+}, {
+    appName?: string | undefined;
+    orbitalFiles?: string | undefined;
+    pagesJson?: string | undefined;
+}>, {
+    appName?: string | undefined;
+    orbitalFiles?: string | undefined;
+    pagesJson?: string | undefined;
+}, {
+    appName?: string | undefined;
+    orbitalFiles?: string | undefined;
+    pagesJson?: string | undefined;
+}, {
+    success: boolean;
+    error: string;
+    appName?: undefined;
+    orbitalCount?: undefined;
+    pageCount?: undefined;
+    schemaPath?: undefined;
+    validation?: undefined;
+} | {
+    success: boolean;
+    appName: string;
+    orbitalCount: number;
+    pageCount: number;
+    schemaPath: string;
+    validation: {
+        valid: boolean;
+        errorCount: number;
+        errors: string[];
+    };
+    error?: undefined;
+}, unknown, "compose_app">;

package/dist/gates/behavior-extract.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Behavior Extract
+ *
+ * Extract per-gate slices from BehaviorSchema for guided mode.
+ * Each function extracts the data a specific gate needs from the golden behavior.
+ *
+ * @packageDocumentation
+ */
+import type { BehaviorSchema } from '@almadar/std/behaviors/types';
+import type { BehaviorGateData } from './types.js';
+/**
+ * Extract all gate-level slices from a BehaviorSchema.
+ * Returns structured data that each gate can consume in guided mode.
+ */
+export declare function extractBehaviorGateData(behavior: BehaviorSchema): BehaviorGateData;
+/**
+ * Get gate-specific slice for a particular trait from extracted data.
+ */
+export declare function getTraitGateData(data: BehaviorGateData, traitName: string): BehaviorGateData['traitLevels'][0] | undefined;
+/**
+ * Get gate-specific slice for a particular transition from extracted data.
+ */
+export declare function getTransitionGateData(data: BehaviorGateData, from: string, event: string): {
+    transition: BehaviorGateData['transitionLevels'][0] | undefined;
+    renderUi: BehaviorGateData['renderUiLevels'][0] | undefined;
+};

package/dist/gates/gate0-application.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Gate 0: Application Decomposition
+ *
+ * NL prompt -> shell OrbitalSchema (orbital names, entity name + id field,
+ * trait names with empty state machines, pages).
+ * Single LLM call with fresh context.
+ *
+ * @packageDocumentation
+ */
+import type { LLMClient } from '@almadar/llm';
+import type { OrbitalSchema } from '@almadar/core/types';
+import type { GateOpts, BehaviorGateData } from './types.js';
+export declare function runGate0(client: LLMClient, prompt: string, opts?: GateOpts, behaviorData?: BehaviorGateData): Promise<OrbitalSchema>;

package/dist/gates/gate05-behavior-match.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Gate 0.5: Behavior Matching
+ *
+ * Given the shell .orb from Gate 0, asks the LLM to select the best-matching
+ * golden behavior from @almadar/std. Loads the matched behavior's exported
+ * .orb file (full OrbitalSchema with entities, state machines, render-ui)
+ * as the goldenOrb for Gates 1-4.
+ *
+ * Only runs in guided mode. Skipped entirely in pure mode.
+ *
+ * @packageDocumentation
+ */
+import type { LLMClient } from '@almadar/llm';
+import type { OrbitalSchema } from '@almadar/core/types';
+import type { GateOpts } from './types.js';
+export { loadGoldenOrb as loadGoldenOrbByName };
+declare function loadGoldenOrb(behaviorName: string): OrbitalSchema | null;
+export interface BehaviorMatchResult {
+    matchedName: string | null;
+    goldenOrb: OrbitalSchema | null;
+}
+/**
+ * Match the prompt against golden behaviors via LLM.
+ * Loads the matched behavior's exported .orb file as goldenOrb.
+ */
+export declare function runGate05(client: LLMClient, prompt: string, orb: OrbitalSchema, opts?: GateOpts): Promise<BehaviorMatchResult>;

package/dist/gates/gate1-orbital.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Gate 1: Orbital Structure
+ *
+ * Enriches each orbital shell with full entity fields, persistence,
+ * collection, trait emits/listens, and pages.
+ * One LLM call per orbital.
+ *
+ * @packageDocumentation
+ */
+import type { LLMClient } from '@almadar/llm';
+import type { OrbitalSchema } from '@almadar/core/types';
+import type { GateOpts, BehaviorGateData } from './types.js';
+/**
+ * Enrich all orbital shells with full entity fields and trait details.
+ * Iterates orbitals with one LLM call each, merges back via replaceOrbital.
+ */
+export declare function runGate1(client: LLMClient, orb: OrbitalSchema, opts?: GateOpts, behaviorData?: BehaviorGateData): Promise<OrbitalSchema>;

package/dist/gates/gate2-trait.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Gate 2: Trait State Machine
+ *
+ * Fills in stateMachine (states, events, transitions with empty effects)
+ * for each trait across all orbitals.
+ * One LLM call per trait.
+ *
+ * @packageDocumentation
+ */
+import type { LLMClient } from '@almadar/llm';
+import type { OrbitalSchema } from '@almadar/core/types';
+import type { GateOpts, BehaviorGateData } from './types.js';
+/**
+ * Fill in state machines for all traits across all orbitals.
+ * Iterates traits with one LLM call each, merges back via replaceTrait.
+ */
+export declare function runGate2(client: LLMClient, orb: OrbitalSchema, opts?: GateOpts, behaviorData?: BehaviorGateData): Promise<OrbitalSchema>;

package/dist/gates/gate3-transition.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Gate 3: Transition Effects
+ *
+ * Fills in guard + non-render effects for each transition across all traits.
+ * One LLM call per transition.
+ *
+ * @packageDocumentation
+ */
+import type { LLMClient } from '@almadar/llm';
+import type { OrbitalSchema } from '@almadar/core/types';
+import type { GateOpts, BehaviorGateData } from './types.js';
+/**
+ * Fill in guards and non-render effects for all transitions.
+ * Iterates all transitions across all traits with one LLM call each.
+ */
+export declare function runGate3(client: LLMClient, orb: OrbitalSchema, opts?: GateOpts, _behaviorData?: BehaviorGateData): Promise<OrbitalSchema>;

package/dist/gates/gate4-render-ui.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Gate 4: Render UI
+ *
+ * Appends render-ui effects to each transition.
+ * One LLM call per transition.
+ * Passes slot context (which states are modal vs main) to every call.
+ *
+ * @packageDocumentation
+ */
+import type { LLMClient } from '@almadar/llm';
+import type { OrbitalSchema } from '@almadar/core/types';
+import type { GateOpts, BehaviorGateData } from './types.js';
+/**
+ * Append render-ui effects to all transitions.
+ * Builds slot context from state machine and passes it to every LLM call.
+ */
+export declare function runGate4(client: LLMClient, orb: OrbitalSchema, opts?: GateOpts, _behaviorData?: BehaviorGateData): Promise<OrbitalSchema>;

package/dist/gates/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Gated Construction Pipeline
+ *
+ * Decomposes .orb program construction into five scoped gates,
+ * each handled by a standalone LLM call with fresh context.
+ * Every gate accepts an OrbitalSchema and returns an enriched OrbitalSchema.
+ *
+ * @packageDocumentation
+ */
+export { runGatePipeline } from './orchestrator.js';
+export { runGate0 } from './gate0-application.js';
+export { runGate05 } from './gate05-behavior-match.js';
+export type { BehaviorMatchResult } from './gate05-behavior-match.js';
+export { runGate1 } from './gate1-orbital.js';
+export { runGate2 } from './gate2-trait.js';
+export { runGate3 } from './gate3-transition.js';
+export { runGate4 } from './gate4-render-ui.js';
+export { deepCloneOrb, replaceOrbital, replaceTrait, replaceTransition } from './merge.js';
+export { extractBehaviorGateData, getTraitGateData, getTransitionGateData } from './behavior-extract.js';
+export { scoreGate0, scoreGate1, scoreGate2, scoreGate3, scoreGate4, scoreOverall, } from './scoring.js';
+export type { GateProvider, GateMode, GateOpts, GatePipelineConfig, GateTimings, GatePipelineResult, GateScore, PipelineScore, BehaviorGateData, } from './types.js';
+export type { OrbitalSchema, OrbitalDefinition, Orbital, Entity, Trait, StateMachine, State, Event, Transition, Effect, Page, Expression, } from '@almadar/core/types';
+export { createDecomposeAppTool, createMatchBehaviorTool, createBuildOrbitalTool, createVerifyAppTool, createUseBehaviorTool, createConnectTool, createComposeTool, } from './agentic/tools.js';