@aria_asi/cli 0.2.25 → 0.2.29

package/dist/runtime/sdk/index.d.ts

@@ -0,0 +1,477 @@
+export interface HarnessClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    harnessPacketUrl?: string;
+    workspaceRoot?: string;
+}
+export interface OwnerTier {
+    hamza: boolean;
+    trustedExec: boolean;
+    roleProfile: string;
+}
+/** Handoff JSON written before a sub-agent spawns. Matches ~/.claude/aria-agent-harness-handoff.json shape. */
+export interface Handoff {
+    writtenAt: string;
+    parentSessionId: string;
+    harnessToken: string;
+    harnessUrl: string;
+    ownerTier: OwnerTier;
+    parentLedgerPath: string;
+    ttlMs: number;
+    /** Path to the harness packet JSON written alongside the handoff for sub-agent cognition bootstrap. */
+    harnessPacketPath?: string;
+}
+export interface SpawnSubAgentArgs {
+    /** What the sub-agent is being asked to do — recorded in the handoff for traceability. */
+    purpose: string;
+    /** List of tool/action names the sub-agent is permitted to call. Informational only — enforcement is harness-side. */
+    allowedActions?: string[];
+    /** Optional defect context (e.g. bug text) to record alongside the handoff. */
+    defectContext?: string;
+    /** Override the JTI used for per-tenant path derivation. Required for client-tier callers. */
+    jti?: string;
+    /** Current session ID — used to derive the parent ledger path. */
+    sessionId: string;
+}
+export interface HarnessPacket {
+    packet: Record<string, unknown>;
+    timestamp: string;
+    version: string;
+}
+export interface PlanDoc {
+    title: string;
+    content?: string;
+    path?: string;
+    references?: string[];
+}
+export interface PlanResponse {
+    ok: boolean;
+    docs: PlanDoc[];
+    files: string[];
+    task: string;
+    reasoning: string;
+}
+export interface HarnessPlan {
+    response: PlanResponse | null;
+    docs: PlanDoc[];
+    files: string[];
+    task?: string;
+}
+export interface HarnessInjection {
+    harness: HarnessPacket;
+    docs: PlanDoc[];
+    files: Record<string, string>;
+    task: string;
+    loadedAt: string;
+    aegisLearnings?: {
+        avoidPatterns: string[];
+        successPatterns: string[];
+        recentPatterns: Array<{
+            name: string;
+            category: string;
+            outcome: string;
+            lesson: string;
+        }>;
+        decisionCount: number;
+        reflectionCount: number;
+    };
+}
+export interface HarnessBindingContext {
+    role: string;
+    sessionId: string;
+    stage: string;
+    intendedAction: string;
+    rationale: string;
+    correlationId?: string;
+    message?: string;
+    userId?: string;
+    userName?: string;
+    platform?: string;
+    roleProfile?: string;
+    currentIssue?: string;
+    linearIssueId?: string;
+    linearIssueUrl?: string;
+    linearState?: string;
+    workingDirectory?: string;
+    filesTouched?: string[];
+    recentProgress?: string[];
+    openRisks?: string[];
+    nextActions?: string[];
+    checkpoint?: Record<string, unknown>;
+    requireGarden?: boolean;
+    researchMode?: 'single-source' | 'multi-source';
+    includeAegisLearnings?: boolean;
+    extraBody?: Record<string, unknown>;
+}
+export interface BoundHarnessPromptResult {
+    prompt: string;
+    packet: HarnessPacket;
+    harnessText: string;
+    bindingBody: Record<string, unknown>;
+}
+export interface RecordDiscoveryArgs {
+    /** Finding text (min 4 chars). */
+    text: string;
+    kind?: 'observation' | 'defect' | 'principle' | 'risk' | 'fix-recipe' | string;
+    refs?: string[];
+    evidence?: string | null;
+    resolution_status?: 'open' | 'resolved' | 'failed' | 'partial' | 'needs-human';
+    source?: string;
+    /** Sub-agent's own session ID. If omitted, derived from handoff parentSessionId + "-sub". */
+    sessionId?: string;
+    /** Client-tier JTI. If omitted, tier is detected from ~/.aria/license.json. */
+    jti?: string;
+}
+export interface RecordDiscoveryResult {
+    ok: boolean;
+    ledger: string;
+    at: string;
+    error?: string;
+}
+export interface VerifyClaimArgs {
+    claim: string;
+    evidence: string | null;
+    sessionId: string;
+    turnId?: string;
+    source?: 'pre-text-gate' | 'manual' | 'sub-agent';
+    context?: Record<string, unknown>;
+}
+export interface VerifyClaimResult {
+    ok: boolean;
+    verdict: 'grounded' | 'ungrounded' | 'partially-grounded';
+    evidenceRefs: string[];
+    storedAt?: string;
+    cognitionCorpusId?: string;
+    error?: string;
+}
+export interface ValidationResult {
+    passed: boolean;
+    violations: string[];
+    severity: 'pass' | 'warn' | 'block';
+    rewritten?: string;
+    gateTriggers: string[];
+}
+export interface ActionCheck {
+    allowed: boolean;
+    reason?: string;
+    requiredGates: string[];
+}
+/**
+ * Result shape for all three Aristotle phases.
+ * Mirrors `AristotleNoorWireResult` in aria-connector's aristotle-noor-wire.ts.
+ * The SDK does NOT import server-side modules (db pool, NoorCore) — all data
+ * arrives via the harness HTTP route `POST /api/harness/aristotle-noor`.
+ */
+export interface AristotlePhaseResult {
+    /** Names of cognitive primitives that fired during this phase. */
+    fired: string[];
+    /** Fitrah hard-gate verdict — if true, the caller MUST emit an honest refusal. */
+    fitrahVetoed: boolean;
+    /** Fitrah alignment score 0–1. */
+    fitrahAlignment: number;
+    /** 8-lens + quality-gate score 0–100 (AFTER phase only; 100 for PRE/MID). */
+    qualityScore: number;
+    /** True when 8-lens gate detected violations — caller should surface re-author signal. */
+    reAuthorSignal: boolean;
+    /** Human-readable notes from each primitive (warnings, skips, etc.). */
+    notes: string[];
+    /** Noor soul-charge scalar (null if manifold not initialized on this call). */
+    soulCharge: number | null;
+    /** Noor manifold drift status string ('aligned'|'stable'|'drifting'|null). */
+    soulManifoldStatus: string | null;
+    /** Ghazali 8-lens verdict string from Noor principle eigenspace ('aligned'|'caution'|'violation'|null). */
+    ghazaliVerdict: string | null;
+    /** Wall-clock latency measured by the harness route (ms). */
+    latencyMs: number;
+    /** True when the dispatch reached the harness; false on transport fault (result is fail-open default). */
+    dispatched: boolean;
+}
+/**
+ * Result shape for Noor eigenspace recognition.
+ * Maps to the `RecognitionResult` + `NoorResponse` shape in noor-core.ts.
+ */
+export interface NoorRecognitionResult {
+    /** Nearest recognized response text from Aria's response library. */
+    nearestText: string;
+    /** Soul distance from manifold centroid (cosine). */
+    soulDistance: number;
+    /** Confidence in the recognition (0–1). */
+    confidence: number;
+    /** Whether the input is within the ethical membrane ∂E. */
+    withinMembrane: boolean;
+    /** Current soul charge Q. */
+    soulCharge: number;
+    /** Top projection components (eigenvector label + weight pairs). */
+    projectionComponents: Array<{
+        eigenvector: string;
+        weight: number;
+    }>;
+    /** Ghazali 8-lens verdict from principle eigenspace, if available. */
+    ghazaliVerdict: string | null;
+    /** Manifold drift status. */
+    manifoldHealth: {
+        charge: number;
+        drift: string;
+        coherence: number;
+    } | null;
+    /** True when the dispatch reached the harness. */
+    dispatched: boolean;
+    /** Wall-clock latency (ms). */
+    latencyMs: number;
+}
+/**
+ * Forge primitive descriptor.
+ * Mirrors the `Primitive` type in noor-forge.ts.
+ */
+export interface NoorForgePrimitive {
+    type: 'http' | 'sql' | 'file_read' | 'file_write' | 'pub_sub';
+    params: Record<string, unknown>;
+}
+/**
+ * Result shape for a Noor Forge operation.
+ * Maps to `ForgeResult` in noor-forge.ts.
+ */
+export interface NoorForgeResult {
+    /** Whether all primitives in the chain executed successfully. */
+    success: boolean;
+    /** Name of the forged tool (slug derived from intent purpose). */
+    toolName: string;
+    /** Whether the intent passed the ethical membrane alignment check. */
+    ethicallyApproved: boolean;
+    /** Wall-clock latency for the full primitive chain (ms). */
+    totalDurationMs: number;
+    /** Per-primitive execution results. */
+    results: Array<{
+        type: string;
+        success: boolean;
+        data: unknown;
+        error?: string;
+        durationMs: number;
+    }>;
+    /** True when the dispatch reached the harness. */
+    dispatched: boolean;
+}
+export declare class HTTPHarnessClient {
+    private static instance;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly harnessPacketUrl;
+    private readonly workspaceRoot;
+    private cachedPacket;
+    private packetLastFetched;
+    private readonly packetTtlMs;
+    constructor(config: HarnessClientConfig);
+    private extractHarnessText;
+    private normalizePlanDocs;
+    private collectPlanFilePaths;
+    private loadFilesByPath;
+    private buildHarnessInjection;
+    private buildHarnessBindingBody;
+    private _tryLoadDiskPacket;
+    static getInstance(config?: HarnessClientConfig): HTTPHarnessClient;
+    static resetInstance(): void;
+    private fetchHarnessPacket;
+    inject(plan: HarnessPlan): Promise<HarnessInjection>;
+    getHarnessPacket(bodyOverride?: Record<string, unknown>): Promise<HarnessPacket>;
+    getBoundHarnessAndPrompt(context: HarnessBindingContext, plan?: Partial<HarnessPlan>): Promise<BoundHarnessPromptResult>;
+    getAegisLearnings(limit?: number): Promise<{
+        avoidPatterns: string[];
+        successPatterns: string[];
+        recentPatterns: Array<{
+            name: string;
+            category: string;
+            outcome: string;
+            lesson: string;
+        }>;
+        decisionCount: number;
+        reflectionCount: number;
+    } | null>;
+    buildSystemPrompt(injection: HarnessInjection): string;
+    get8LensBlock(): string;
+    validateOutput(text: string, sessionId: string): Promise<ValidationResult>;
+    checkAction(action: 'deploy' | 'build' | 'write' | 'delete', target: string): Promise<ActionCheck>;
+    gardenTurn(sessionId: string, message: string, response: string, userId?: string): Promise<void>;
+    consult(args: {
+        brief: string;
+        sessionId: string;
+        userId?: string;
+        roleProfile?: string;
+        expectStructuredOutput?: boolean;
+        model?: string;
+        isCreativeMode?: boolean;
+        internalConsult?: boolean;
+    }): Promise<{
+        response: string;
+        metadata?: Record<string, unknown>;
+    }>;
+    consultWithTools(args: {
+        brief: string;
+        sessionId: string;
+        userId?: string;
+        model?: string;
+        tools: Array<{
+            name: string;
+            description: string;
+            argsSchema?: string;
+        }>;
+        executor: (toolName: string, toolArgs: Record<string, unknown>) => Promise<string>;
+        maxIterations?: number;
+    }): Promise<{
+        finalText: string;
+        toolCalls: Array<{
+            name: string;
+            args: Record<string, unknown>;
+            result: string;
+        }>;
+        iterations: number;
+    }>;
+    spawnSubAgent(args: SpawnSubAgentArgs): Promise<Handoff>;
+    /**
+     * Returns the environment variables to set for a spawned sub-agent process
+     * so it inherits the parent's harness packet without an extra HTTP call.
+     * Call after spawnSubAgent() — uses the returned handoff.harnessPacketPath.
+     *
+     * Usage:
+     *   const handoff = await sdk.spawnSubAgent(args);
+     *   const env = sdk.subAgentEnv(handoff);
+     *   // pass env to your process spawn / Agent tool env block
+     */
+    subAgentEnv(handoff: Handoff): Record<string, string>;
+    /** Pulls sub-agent ledger entries newer than the handoff timestamp and appends
+     * them to the parent ledger, deduplicating by `text` prefix (first 100 chars). */
+    mergeSubAgentLedger(parentSessionId: string, _subAgentSessionId?: string, jti?: string): Promise<{
+        merged: number;
+        skipped: number;
+    }>;
+    recordDiscovery(args: RecordDiscoveryArgs): Promise<RecordDiscoveryResult>;
+    verifyClaim(args: VerifyClaimArgs): Promise<VerifyClaimResult>;
+    postJson<T = unknown>(url: string, body: unknown, extraHeaders?: Record<string, string>): Promise<{
+        ok: true;
+        status: number;
+        data: T;
+    } | {
+        ok: false;
+        status: number;
+        errorBody: string;
+    }>;
+    /**
+     * ARISTOTLE PRE-PHASE
+     * Fires before an LLM call or tool action. Runs: Fitrah hard-gate,
+     * wisdom pull (principles + decisions), research pull, DeepSoulBridge,
+     * and CleanCognition substrate check.
+     *
+     * Throws on transport-level failures per feedback_non_blocking_errors_unacceptable.md.
+     * If Fitrah vetoes, result.fitrahVetoed === true — caller MUST emit a refusal,
+     * not silently continue.
+     *
+     * @param message   The user message or intent string being processed.
+     * @param sessionId Session ID for telemetry + hive routing.
+     * @param context   Optional context overrides (userId, isHamza, tier, etc.).
+     */
+    aristotlePre(message: string, sessionId: string, context?: {
+        userId?: string;
+        isHamza?: boolean;
+        isGroupChat?: boolean;
+        tier?: string;
+    }): Promise<AristotlePhaseResult>;
+    /**
+     * ARISTOTLE MID-PHASE
+     * Fires after context is built but before the LLM call. Runs: MetaCognitive
+     * confidence snapshot and ethical keyword check on the planned approach.
+     *
+     * @param message         Original user message.
+     * @param sessionId       Session ID.
+     * @param plannedApproach The drafted approach / plan string for mid-flight check.
+     * @param context         Optional context overrides.
+     */
+    aristotleMid(message: string, sessionId: string, plannedApproach: string, context?: {
+        userId?: string;
+        tier?: string;
+    }): Promise<AristotlePhaseResult>;
+    /**
+     * ARISTOTLE POST-PHASE
+     * Fires after the LLM response, before emission. Runs: 8-Lens Detector,
+     * Predictor, SelfReflection (on high-stakes turns), and quality scoring.
+     *
+     * If result.reAuthorSignal === true, the response has 8-lens violations —
+     * per doctrine the caller MUST surface the signal, never silently strip.
+     *
+     * @param message   Original user message.
+     * @param response  The LLM-generated response to gate.
+     * @param sessionId Session ID.
+     * @param context   Optional context overrides (tier, isFirstOfSession).
+     */
+    aristotlePost(message: string, response: string, sessionId: string, context?: {
+        userId?: string;
+        tier?: string;
+        isFirstOfSession?: boolean;
+    }): Promise<AristotlePhaseResult>;
+    /**
+     * NOOR RECOGNIZE (Kashf — eigenspace recognition, not generation)
+     * Projects the query string (via harness-side embedding) onto Aria's
+     * eigenspace manifold and returns the nearest recognized response + soul
+     * distance + ethical membrane status + Ghazali 8-lens verdict.
+     *
+     * The harness routes the query through the manifold service (gRPC) if
+     * NOOR_EIGENSPACE_SOURCE=manifold, otherwise uses local eigenspace.
+     *
+     * @param query   The input string to recognize on the manifold.
+     * @param context Optional context (sessionId, userId) for telemetry.
+     */
+    noorRecognize(query: string, context?: {
+        sessionId?: string;
+        userId?: string;
+    }): Promise<NoorRecognitionResult>;
+    /**
+     * NOOR FORGE — self-generated tool invocation via 5 primitives
+     * Composes a named primitive chain (http, sql, file_read, file_write, pub_sub)
+     * and executes it through the harness-side NoorForge engine. The harness
+     * applies the ethical membrane check (checkEthicalAlignment) before any
+     * primitive fires — rejected intents return success=false, ethicallyApproved=false.
+     *
+     * @param intent      Description of what the forged tool should accomplish.
+     * @param primitives  Ordered list of primitive descriptors to execute in sequence.
+     * @param context     Optional context for telemetry.
+     */
+    noorForge(intent: string, primitives: NoorForgePrimitive[], context?: {
+        sessionId?: string;
+        userId?: string;
+    }): Promise<NoorForgeResult>;
+    /**
+     * Harness consult with Aristotle 3-phase wrapping.
+     *
+     * Flow:
+     *   1. aristotlePre()  — Fitrah gate, wisdom, research, soul state
+     *   2. getBoundHarnessAndPrompt() — packet + system prompt
+     *   3. aristotleMid()  — MetaCognitive + ethical check (if plannedApproach provided)
+     *   4. [caller calls LLM with the returned prompt]
+     *   5. Call aristotlePost() from the caller with the LLM response
+     *      (post-phase is caller-side because the SDK doesn't own the LLM call)
+     *
+     * Returns the BoundHarnessPromptResult augmented with the pre-phase result.
+     * If Fitrah vetoes, throws — the caller must handle the veto (emit refusal).
+     *
+     * @param context          HarnessBindingContext (same shape as getBoundHarnessAndPrompt).
+     * @param plan             Optional plan docs / files (same shape as getBoundHarnessAndPrompt).
+     * @param options          Aristotle control options.
+     * @param options.aristotleEnabled  Whether Aristotle fires. Default true for this method.
+     * @param options.plannedApproach   Optional planned approach string — activates mid-phase.
+     * @param options.tier              Tier hint for Aristotle ('owner'|'client'|etc.).
+     */
+    getBoundHarnessAndPromptWithAristotle(context: HarnessBindingContext, plan?: Partial<HarnessPlan>, options?: {
+        aristotleEnabled?: boolean;
+        plannedApproach?: string;
+        tier?: string;
+    }): Promise<BoundHarnessPromptResult & {
+        aristotlePre: AristotlePhaseResult | null;
+        aristotleMid: AristotlePhaseResult | null;
+    }>;
+    private fetchWithRetry;
+}
+export declare const harness: {
+    getInstance: typeof HTTPHarnessClient.getInstance;
+    resetInstance: typeof HTTPHarnessClient.resetInstance;
+};
+export declare function bindingContext(role: string, sessionId: string, stage: string, intendedAction: string, rationale: string): HarnessBindingContext;
+export declare function getBoundHarnessAndPrompt(context: HarnessBindingContext, plan?: Partial<HarnessPlan>, client?: HTTPHarnessClient): Promise<BoundHarnessPromptResult>;
+export * from './runWithCognition.js';