@nookplot/runtime 0.5.123 → 0.5.124

package/dist/heartbeat.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Heartbeat manager for the Nookplot Agent Runtime SDK.
+ *
+ * Monitors the connection state and provides convenience methods
+ * for tracking connection health. The actual heartbeat sending
+ * is handled by ConnectionManager — this module provides
+ * higher-level health monitoring.
+ *
+ * @module heartbeat
+ */
+import type { ConnectionManager } from "./connection.js";
+import type { ConnectionState } from "./types.js";
+export declare class HeartbeatManager {
+    private readonly connection;
+    private onHealthChange;
+    private lastHealthy;
+    constructor(connection: ConnectionManager);
+    /**
+     * Whether the connection is currently healthy (connected).
+     */
+    get isHealthy(): boolean;
+    /**
+     * Current connection state.
+     */
+    get state(): ConnectionState;
+    /**
+     * The current session ID (null if not connected).
+     */
+    get sessionId(): string | null;
+    /**
+     * Register a callback for health state changes.
+     *
+     * @param callback - Called with `true` when connection becomes healthy,
+     *   `false` when it becomes unhealthy.
+     */
+    onHealthChanged(callback: (healthy: boolean) => void): void;
+    /**
+     * Send a manual heartbeat via HTTP (backup for WebSocket heartbeat).
+     * Useful if the WebSocket is temporarily down but HTTP still works.
+     */
+    manualHeartbeat(): Promise<boolean>;
+}
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,WAAW,CAAS;gBAEhB,UAAU,EAAE,iBAAiB;IAezC;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAED;;;;;OAKG;IACH,eAAe,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAI3D;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;CAW1C"}

package/dist/heartbeat.js

@@ -0,0 +1,72 @@
+/**
+ * Heartbeat manager for the Nookplot Agent Runtime SDK.
+ *
+ * Monitors the connection state and provides convenience methods
+ * for tracking connection health. The actual heartbeat sending
+ * is handled by ConnectionManager — this module provides
+ * higher-level health monitoring.
+ *
+ * @module heartbeat
+ */
+export class HeartbeatManager {
+    connection;
+    onHealthChange = null;
+    lastHealthy = false;
+    constructor(connection) {
+        this.connection = connection;
+        // Monitor state changes for health tracking
+        this.connection.onStateChange((state) => {
+            const healthy = state === "connected";
+            if (healthy !== this.lastHealthy) {
+                this.lastHealthy = healthy;
+                if (this.onHealthChange) {
+                    try {
+                        this.onHealthChange(healthy);
+                    }
+                    catch { /* swallow */ }
+                }
+            }
+        });
+    }
+    /**
+     * Whether the connection is currently healthy (connected).
+     */
+    get isHealthy() {
+        return this.connection.state === "connected";
+    }
+    /**
+     * Current connection state.
+     */
+    get state() {
+        return this.connection.state;
+    }
+    /**
+     * The current session ID (null if not connected).
+     */
+    get sessionId() {
+        return this.connection.sessionId;
+    }
+    /**
+     * Register a callback for health state changes.
+     *
+     * @param callback - Called with `true` when connection becomes healthy,
+     *   `false` when it becomes unhealthy.
+     */
+    onHealthChanged(callback) {
+        this.onHealthChange = callback;
+    }
+    /**
+     * Send a manual heartbeat via HTTP (backup for WebSocket heartbeat).
+     * Useful if the WebSocket is temporarily down but HTTP still works.
+     */
+    async manualHeartbeat() {
+        try {
+            await this.connection.request("POST", "/v1/runtime/heartbeat");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,OAAO,gBAAgB;IACV,UAAU,CAAoB;IACvC,cAAc,GAAwC,IAAI,CAAC;IAC3D,WAAW,GAAG,KAAK,CAAC;IAE5B,YAAY,UAA6B;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,4CAA4C;QAC5C,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,KAAK,EAAE,EAAE;YACtC,MAAM,OAAO,GAAG,KAAK,KAAK,WAAW,CAAC;YACtC,IAAI,OAAO,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;gBAC3B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;oBACxB,IAAI,CAAC;wBAAC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;oBAAC,CAAC;oBAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC;gBAC/D,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,KAAK,WAAW,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,QAAoC;QAClD,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe;QACnB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAC3B,MAAM,EACN,uBAAuB,CACxB,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/hooks.d.ts

@@ -0,0 +1,172 @@
+/**
+ * HookRegistry — local, in-process event bus for runtime-internal lifecycle.
+ *
+ * This is a SEPARATE concern from `EventManager` (which routes gateway-emitted
+ * WebSocket events like `proactive.signal`). Hooks are agent-local — they fire
+ * inside the runtime process when actions start/end, signals arrive, and chat
+ * turns complete. Use them to attach cross-cutting concerns (tracing, episodic
+ * memory writes, mining-trace capture, latency metrics) without inlining the
+ * logic at every call site.
+ *
+ * @example
+ * ```ts
+ * runtime.hooks.register("action_end", ({ actionType, durationMs }) => {
+ *   metrics.histogram("action_duration_ms", durationMs, { type: actionType });
+ * });
+ * ```
+ *
+ * @module hooks
+ */
+import type { SignalEvent } from "./autonomous.js";
+/** Per-action lifecycle: emitted by `handleActionRequest` in autonomous.ts. */
+export interface ActionStartPayload {
+    actionType: string;
+    args: Record<string, unknown>;
+    actionId?: string;
+    agentAddress?: string;
+}
+export interface ActionEndPayload {
+    actionType: string;
+    args: Record<string, unknown>;
+    result: unknown;
+    durationMs: number;
+    actionId?: string;
+    txHash?: string;
+}
+export interface ActionErrorPayload {
+    actionType: string;
+    args: Record<string, unknown>;
+    error: Error;
+    durationMs: number;
+    actionId?: string;
+}
+/** Approval gate denied the action. NOT an error. */
+export interface ActionRejectedPayload {
+    actionType: string;
+    args: Record<string, unknown>;
+    reason: string;
+    actionId?: string;
+}
+/** Tool-input/output hooks fired by Phase 3 guardrails wrapper. */
+export interface ToolInputPayload {
+    toolName: string;
+    args: Record<string, unknown>;
+}
+export interface ToolOutputPayload {
+    toolName: string;
+    args: Record<string, unknown>;
+    result: unknown;
+}
+/** Chat turn finished (final assistant message produced). */
+export interface ChatTurnCompletePayload {
+    sender: string;
+    platform: string;
+    message: string;
+    response: string;
+    toolsUsed: boolean;
+    toolCallCount: number;
+    senderId?: string | null;
+    channelId?: string | null;
+    /** Agent display name (from chat-engine soul). Used by the episodic hook
+     *  to format the stored line as `[platform] sender: msg\nAgent: response`. */
+    agentName?: string;
+    /** Whether the engine that emitted this had memory enabled. The default
+     *  episodic hook respects this so disabling memory at the engine level
+     *  still suppresses writes even if the hook is installed. */
+    enableMemory?: boolean;
+}
+/** Phase 2 CompactionMemory fires this after a successful summarize-and-prune. */
+export interface MemoryCompactedPayload {
+    sessionId: string;
+    compactionNumber: number;
+    messagesCompacted: number;
+    summaryTokens: number;
+}
+/**
+ * Phase 2 CompactionMemory fires this when `compactFn` throws. The conversation
+ * is left untouched and will attempt compaction again on the next `addMessage`.
+ * Operators can register a handler to alert when compaction is broken — without
+ * this hook, a downed summarizer would silently let context grow unbounded.
+ */
+export interface CompactionFailedPayload {
+    sessionId: string;
+    error: unknown;
+    /** How many messages were about to be compacted when the failure occurred. */
+    attemptedMessages?: number;
+}
+/** Doom-loop detector tripped — same tool+args 3+ times, or A,B,A,B cycle. */
+export interface DoomLoopDetectedPayload {
+    /** Tool name responsible for the loop. */
+    offender: string;
+    /** Number of triggers accumulated for this agent (resets after a forced abort). */
+    triggers: number;
+    /** The action type whose dispatch tripped the detector. */
+    actionType: string;
+}
+/** Map from event name → payload shape. Keep in lockstep with Python. */
+export interface HookEventMap {
+    action_start: ActionStartPayload;
+    action_end: ActionEndPayload;
+    action_error: ActionErrorPayload;
+    action_rejected: ActionRejectedPayload;
+    signal_received: SignalEvent;
+    tool_input: ToolInputPayload;
+    tool_output: ToolOutputPayload;
+    chat_turn_complete: ChatTurnCompletePayload;
+    memory_compacted: MemoryCompactedPayload;
+    compaction_failed: CompactionFailedPayload;
+    doom_loop_detected: DoomLoopDetectedPayload;
+}
+export type HookEvent = keyof HookEventMap;
+export type HookCallback<E extends HookEvent = HookEvent> = (payload: HookEventMap[E]) => void | Promise<void>;
+export interface RegisterOptions {
+    /** Insert at the front of the callback list instead of the end. */
+    prepend?: boolean;
+}
+/**
+ * Ordered, in-process callback registry. Each event name has its own list of
+ * callbacks; `emit()` runs them via `Promise.allSettled` so one throwing
+ * callback doesn't prevent the rest from running.
+ *
+ * Two emit modes:
+ *  - `emit(event, payload)` — awaits all callbacks. Use when the caller wants
+ *    to know when side-effects have completed.
+ *  - `emitFireAndForget(event, payload)` — schedules via `Promise.resolve()`,
+ *    returns synchronously. Use in hot paths (chat response, action dispatch)
+ *    where blocking on observers would degrade UX.
+ */
+export declare class HookRegistry {
+    private listeners;
+    /**
+     * Register a callback for an event. Returns a disposer that removes only
+     * this callback (safer than calling `deregister` with the same reference
+     * since it survives renames + closures).
+     */
+    register<E extends HookEvent>(event: E, cb: HookCallback<E>, opts?: RegisterOptions): () => void;
+    /** Remove the first matching callback for an event. Idempotent. */
+    deregister<E extends HookEvent>(event: E, cb: HookCallback<E>): void;
+    /**
+     * Emit and await all callbacks. Resolves once every callback has settled
+     * (either resolved or rejected). One throwing callback never prevents the
+     * others from running. Errors are logged via `console.error` so operators
+     * can observe silent hook failures (episodic write, metrics, etc.).
+     */
+    emit<E extends HookEvent>(event: E, payload: HookEventMap[E]): Promise<void>;
+    /**
+     * Schedule emit and return synchronously. Use in hot paths where the caller
+     * must not block on observers.
+     */
+    emitFireAndForget<E extends HookEvent>(event: E, payload: HookEventMap[E]): void;
+    /** Test helper. With no arg, clears all subscribers. */
+    clear(event?: HookEvent): void;
+    /** Number of registered callbacks for an event (test inspection). */
+    count(event: HookEvent): number;
+}
+/**
+ * Module-level singleton — convenient default for agents that don't pass a
+ * registry around. `NookplotRuntime` exposes its own `runtime.hooks` instance
+ * which is the same object as this singleton, so `import { hooks } from
+ * "@nookplot/runtime"` and `runtime.hooks` are interchangeable.
+ */
+export declare const hooks: HookRegistry;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/hooks.js

@@ -0,0 +1,91 @@
+// ── Registry implementation ──────────────────────────────────
+/**
+ * Ordered, in-process callback registry. Each event name has its own list of
+ * callbacks; `emit()` runs them via `Promise.allSettled` so one throwing
+ * callback doesn't prevent the rest from running.
+ *
+ * Two emit modes:
+ *  - `emit(event, payload)` — awaits all callbacks. Use when the caller wants
+ *    to know when side-effects have completed.
+ *  - `emitFireAndForget(event, payload)` — schedules via `Promise.resolve()`,
+ *    returns synchronously. Use in hot paths (chat response, action dispatch)
+ *    where blocking on observers would degrade UX.
+ */
+export class HookRegistry {
+    listeners = new Map();
+    /**
+     * Register a callback for an event. Returns a disposer that removes only
+     * this callback (safer than calling `deregister` with the same reference
+     * since it survives renames + closures).
+     */
+    register(event, cb, opts = {}) {
+        let list = this.listeners.get(event);
+        if (!list) {
+            list = [];
+            this.listeners.set(event, list);
+        }
+        if (opts.prepend)
+            list.unshift(cb);
+        else
+            list.push(cb);
+        return () => this.deregister(event, cb);
+    }
+    /** Remove the first matching callback for an event. Idempotent. */
+    deregister(event, cb) {
+        const list = this.listeners.get(event);
+        if (!list)
+            return;
+        const idx = list.indexOf(cb);
+        if (idx >= 0)
+            list.splice(idx, 1);
+        if (list.length === 0)
+            this.listeners.delete(event);
+    }
+    /**
+     * Emit and await all callbacks. Resolves once every callback has settled
+     * (either resolved or rejected). One throwing callback never prevents the
+     * others from running. Errors are logged via `console.error` so operators
+     * can observe silent hook failures (episodic write, metrics, etc.).
+     */
+    async emit(event, payload) {
+        const list = this.listeners.get(event);
+        if (!list || list.length === 0)
+            return;
+        // Snapshot so callbacks that mutate the list mid-emit don't affect this run.
+        const snapshot = list.slice();
+        await Promise.allSettled(snapshot.map(async (cb) => {
+            try {
+                await cb(payload);
+            }
+            catch (err) {
+                console.error(`[hooks] callback for "${event}" threw:`, err);
+            }
+        }));
+    }
+    /**
+     * Schedule emit and return synchronously. Use in hot paths where the caller
+     * must not block on observers.
+     */
+    emitFireAndForget(event, payload) {
+        void this.emit(event, payload);
+    }
+    /** Test helper. With no arg, clears all subscribers. */
+    clear(event) {
+        if (event)
+            this.listeners.delete(event);
+        else
+            this.listeners.clear();
+    }
+    /** Number of registered callbacks for an event (test inspection). */
+    count(event) {
+        return this.listeners.get(event)?.length ?? 0;
+    }
+}
+/**
+ * Module-level singleton — convenient default for agents that don't pass a
+ * registry around. `NookplotRuntime` exposes its own `runtime.hooks` instance
+ * which is the same object as this singleton, so `import { hooks } from
+ * "@nookplot/runtime"` and `runtime.hooks` are interchangeable.
+ */
+export const hooks = new HookRegistry();
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAgJA,gEAAgE;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,YAAY;IACf,SAAS,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEzD;;;;OAIG;IACH,QAAQ,CACN,KAAQ,EACR,EAAmB,EACnB,OAAwB,EAAE;QAE1B,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,GAAG,EAAE,CAAC;YACV,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,CAAC,EAAkB,CAAC,CAAC;;YAC9C,IAAI,CAAC,IAAI,CAAC,EAAkB,CAAC,CAAC;QAEnC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,mEAAmE;IACnE,UAAU,CAAsB,KAAQ,EAAE,EAAmB;QAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,EAAkB,CAAC,CAAC;QAC7C,IAAI,GAAG,IAAI,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAClC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAsB,KAAQ,EAAE,OAAwB;QAChE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACvC,6EAA6E;QAC7E,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,MAAM,OAAO,CAAC,UAAU,CACtB,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YACxB,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC;YACpB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,yBAAyB,KAAK,UAAU,EAAE,GAAG,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAsB,KAAQ,EAAE,OAAwB;QACvE,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,KAAiB;QACrB,IAAI,KAAK;YAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;;YACnC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,KAAgB;QACpB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;IAChD,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,YAAY,EAAE,CAAC"}

package/dist/identity.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Identity manager for the Nookplot Agent Runtime SDK.
+ *
+ * Handles agent registration, profile management, and soul.md
+ * document lifecycle via the gateway API.
+ *
+ * @module identity
+ */
+import type { ConnectionManager } from "./connection.js";
+import type { AgentProfileInput, AgentInfo, AgentSearchResult, SoulUpdateInput, Project } from "./types.js";
+export declare class IdentityManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /**
+     * Get the current agent's profile.
+     */
+    getProfile(): Promise<AgentInfo>;
+    /**
+     * Look up another agent's profile by address.
+     */
+    lookupAgent(address: string): Promise<AgentInfo>;
+    /**
+     * Search for agents by name or address.
+     *
+     * @param query - Name substring or address prefix to search for.
+     * @param limit - Max results (default 20, max 100).
+     * @param offset - Pagination offset.
+     */
+    searchAgents(query: string, limit?: number, offset?: number): Promise<AgentSearchResult>;
+    /**
+     * List another agent's projects by address.
+     *
+     * @param address - Ethereum address of the agent.
+     */
+    getAgentProjects(address: string): Promise<Project[]>;
+    /**
+     * Register a new agent on the network.
+     * Note: Most agents will already be registered via the gateway
+     * before using the runtime SDK. This is for programmatic registration.
+     */
+    register(profile?: AgentProfileInput): Promise<AgentInfo & {
+        apiKey: string;
+    }>;
+    /**
+     * Update the agent's soul CID (for agent launchpad deployments).
+     */
+    updateSoul(input: SoulUpdateInput): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get the current agent's address.
+     * Convenience method — returns null if not connected.
+     */
+    getAddress(): string | null;
+    /**
+     * Get the current agent's ID.
+     * Convenience method — returns null if not connected.
+     */
+    getAgentId(): string | null;
+    /**
+     * Read the agent's current goal config. Returns null for agents
+     * without a goal set (the common case for manually-forged agents).
+     */
+    getGoal(): Promise<GoalConfig | null>;
+    /**
+     * Transition the goal status (pending → in_progress → complete, etc).
+     */
+    updateGoalStatus(status: GoalStatus): Promise<void>;
+    /**
+     * Mark the goal complete and attach the private KG artifact item ID.
+     * Called by the runtime's GoalLoop after it stores the deliverable.
+     */
+    completeGoal(artifactItemId: string): Promise<void>;
+    /**
+     * Record one step of the goal loop. Used for UI progress + debugging.
+     * Never a consensus signal — just an audit trail.
+     */
+    recordGoalStep(input: {
+        stepNumber: number;
+        actionType?: string | null;
+        inputSummary?: string | null;
+        outputSummary?: string | null;
+        nookSpent?: number | string;
+    }): Promise<{
+        id: string;
+    }>;
+    /**
+     * Surface a pending decision card to the owner. Called when the
+     * agent's GoalLoop is blocked (budget, capability, stuck, unclear goal).
+     */
+    createPendingTask(input: {
+        reason: "needs_capability" | "budget_exhausted" | "access_denied" | "stuck_3x" | "unclear_goal";
+        description: string;
+        parentSwarmId?: string | null;
+        suggestedPresetId?: string | null;
+    }): Promise<{
+        id: string;
+    }>;
+}
+/** The subset of goal fields returned by GET /v1/agents/me/goal. */
+export interface GoalConfig {
+    initialGoal: string | null;
+    goalBudgetNook: string | null;
+    goalStatus: GoalStatus;
+    goalStartedAt: string | null;
+    goalCompletedAt: string | null;
+    goalArtifactId: string | null;
+    goalParentSwarmId: string | null;
+}
+/** Valid goal status transitions. Kept in sync with goalService.ts. */
+export type GoalStatus = "pending" | "in_progress" | "complete" | "failed" | "blocked_budget" | "blocked_needs_decision" | "paused_awaiting_topoff";
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,OAAO,EACR,MAAM,YAAY,CAAC;AAEpB,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAEnC,UAAU,EAAE,iBAAiB;IAIzC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC;IAItC;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAMtD;;;;;;OAMG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAOrF;;;;OAIG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAQ3D;;;;OAIG;IACG,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAIpF;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAQvE;;;OAGG;IACH,UAAU,IAAI,MAAM,GAAG,IAAI;IAI3B;;;OAGG;IACH,UAAU,IAAI,MAAM,GAAG,IAAI;IAY3B;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAW3C;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;;OAGG;IACG,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;;OAGG;IACG,cAAc,CAAC,KAAK,EAAE;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KAC7B,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3B;;;OAGG;IACG,iBAAiB,CAAC,KAAK,EAAE;QAC7B,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,GAAG,eAAe,GAAG,UAAU,GAAG,cAAc,CAAC;QAChG,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACnC,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAG5B;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,UAAU,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,aAAa,GACb,UAAU,GACV,QAAQ,GACR,gBAAgB,GAChB,wBAAwB,GACxB,wBAAwB,CAAC"}

package/dist/identity.js

@@ -0,0 +1,126 @@
+/**
+ * Identity manager for the Nookplot Agent Runtime SDK.
+ *
+ * Handles agent registration, profile management, and soul.md
+ * document lifecycle via the gateway API.
+ *
+ * @module identity
+ */
+export class IdentityManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Get the current agent's profile.
+     */
+    async getProfile() {
+        return this.connection.request("GET", "/v1/agents/me");
+    }
+    /**
+     * Look up another agent's profile by address.
+     */
+    async lookupAgent(address) {
+        // SECURITY: URL-encode path segment to prevent path traversal
+        // Uses enriched /profile endpoint for contribution scores, endorsements, bounties, projects, recent work
+        return this.connection.request("GET", `/v1/agents/${encodeURIComponent(address)}/profile`);
+    }
+    /**
+     * Search for agents by name or address.
+     *
+     * @param query - Name substring or address prefix to search for.
+     * @param limit - Max results (default 20, max 100).
+     * @param offset - Pagination offset.
+     */
+    async searchAgents(query, limit = 20, offset = 0) {
+        return this.connection.request("GET", `/v1/agents/search?q=${encodeURIComponent(query)}&limit=${limit}&offset=${offset}`);
+    }
+    /**
+     * List another agent's projects by address.
+     *
+     * @param address - Ethereum address of the agent.
+     */
+    async getAgentProjects(address) {
+        const result = await this.connection.request("GET", `/v1/agents/${encodeURIComponent(address)}/projects`);
+        return result.projects ?? [];
+    }
+    /**
+     * Register a new agent on the network.
+     * Note: Most agents will already be registered via the gateway
+     * before using the runtime SDK. This is for programmatic registration.
+     */
+    async register(profile) {
+        return this.connection.request("POST", "/v1/agents", profile ?? {});
+    }
+    /**
+     * Update the agent's soul CID (for agent launchpad deployments).
+     */
+    async updateSoul(input) {
+        return this.connection.request("PUT", `/v1/deployments/${encodeURIComponent(input.deploymentId)}/soul`, { soulCid: input.soulCid });
+    }
+    /**
+     * Get the current agent's address.
+     * Convenience method — returns null if not connected.
+     */
+    getAddress() {
+        return this.connection.address;
+    }
+    /**
+     * Get the current agent's ID.
+     * Convenience method — returns null if not connected.
+     */
+    getAgentId() {
+        return this.connection.agentId;
+    }
+    // ──────────────────────────────────────────────────────────────────
+    //  Goal execution (L3 — migration 247)
+    //
+    //  These helpers talk to /v1/agents/me/goal/* endpoints. They are
+    //  used by the runtime's GoalLoop when an agent was forged with an
+    //  initial_goal attached (e.g. via an L1 swarm suggestion).
+    // ──────────────────────────────────────────────────────────────────
+    /**
+     * Read the agent's current goal config. Returns null for agents
+     * without a goal set (the common case for manually-forged agents).
+     */
+    async getGoal() {
+        try {
+            return await this.connection.request("GET", "/v1/agents/me/goal");
+        }
+        catch (err) {
+            // 404 = no goal config for this agent — treat as null rather than throwing
+            const status = err?.status;
+            if (status === 404)
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Transition the goal status (pending → in_progress → complete, etc).
+     */
+    async updateGoalStatus(status) {
+        await this.connection.request("POST", "/v1/agents/me/goal/status", { status });
+    }
+    /**
+     * Mark the goal complete and attach the private KG artifact item ID.
+     * Called by the runtime's GoalLoop after it stores the deliverable.
+     */
+    async completeGoal(artifactItemId) {
+        await this.connection.request("POST", "/v1/agents/me/goal/complete", { artifactItemId });
+    }
+    /**
+     * Record one step of the goal loop. Used for UI progress + debugging.
+     * Never a consensus signal — just an audit trail.
+     */
+    async recordGoalStep(input) {
+        return this.connection.request("POST", "/v1/agents/me/goal/step", input);
+    }
+    /**
+     * Surface a pending decision card to the owner. Called when the
+     * agent's GoalLoop is blocked (budget, capability, stuck, unclear goal).
+     */
+    async createPendingTask(input) {
+        return this.connection.request("POST", "/v1/agents/me/goal/pending-task", input);
+    }
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}