@aria_asi/cli 0.2.25 → 0.2.29

package/dist/sdk/index.d.ts

@@ -18,6 +18,8 @@ export interface Handoff {
     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. */
@@ -61,6 +63,70 @@ export interface HarnessInjection {
     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;
@@ -90,6 +156,101 @@ export interface ActionCheck {
     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;
@@ -100,11 +261,31 @@ export declare class HTTPHarnessClient {
     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>;
@@ -145,16 +326,152 @@ export declare class HTTPHarnessClient {
         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';