@aionis/openclaw-adapter 0.1.0

package/dist/adapter/loop-control-adapter.js

@@ -0,0 +1,347 @@
+import { createHash, randomUUID } from "node:crypto";
+import { DEFAULT_THRESHOLDS } from "../types/config.js";
+import { classifyBroadScan, classifyBroadTest, inferProgress, summarizeToolResult } from "./heuristics.js";
+import { createRunState, hashStable, LoopStateStore } from "./state.js";
+export class AionisLoopControlAdapter {
+    client;
+    config;
+    states = new LoopStateStore();
+    constructor(client, config) {
+        this.client = client;
+        const mergedThresholds = { ...DEFAULT_THRESHOLDS, ...(config.thresholds ?? {}) };
+        this.config = {
+            ...config,
+            thresholds: mergedThresholds,
+            strictToolBlocking: config.strictToolBlocking ?? true,
+            replayDispatchEnabled: config.replayDispatchEnabled ?? true,
+            handoffFallbackEnabled: config.handoffFallbackEnabled ?? true,
+        };
+    }
+    sessionStart(ctx) {
+        const scope = this.config.scopeResolver(ctx);
+        const state = createRunState({
+            stateId: ctx.sessionId,
+            scope,
+            agentId: ctx.agentId,
+            sessionKey: ctx.sessionKey,
+            sessionId: ctx.sessionId,
+            workspaceDir: ctx.workspaceDir,
+        });
+        this.states.upsert(state);
+        return this.states.link(state, ctx.sessionId, ctx.sessionKey);
+    }
+    sessionEnd(sessionId) {
+        const state = this.states.get(sessionId);
+        if (state) {
+            this.states.deleteAllFor(state);
+            return;
+        }
+        this.states.delete(sessionId);
+    }
+    async beforeAgentStart(event, ctx) {
+        const state = this.ensureState({
+            prompt: event.prompt,
+            agentId: ctx.agentId,
+            sessionKey: ctx.sessionKey,
+            sessionId: ctx.sessionId,
+            workspaceDir: ctx.workspaceDir,
+        });
+        if (!this.client.contextAssemble)
+            return undefined;
+        const candidates = this.extractCandidateTools(event.messages);
+        const out = await this.client.contextAssemble({
+            scope: state.scope,
+            queryText: event.prompt,
+            context: {
+                source: "openclaw-adapter.before_agent_start",
+                agent_id: ctx.agentId,
+                session_key: ctx.sessionKey,
+                session_id: ctx.sessionId,
+                trigger: ctx.trigger,
+            },
+            toolCandidates: candidates,
+        });
+        const merged = out?.layered_context?.merged_text?.trim();
+        const decision = out?.tools ?? undefined;
+        this.captureDecision(state, decision ?? undefined);
+        if (!merged)
+            return undefined;
+        return { prependContext: `<aionis-context>\n${merged}\n</aionis-context>` };
+    }
+    async beforeToolCall(event, ctx) {
+        const state = this.ensureState({
+            agentId: ctx.agentId,
+            sessionKey: ctx.sessionKey,
+            sessionId: ctx.sessionId,
+            runId: event.runId ?? ctx.runId,
+            workspaceDir: ctx.workspaceDir,
+        });
+        const currentToolHash = hashStable(event.params);
+        state.stepCount += 1;
+        state.sameToolStreak = state.lastToolName === event.toolName && state.lastToolParamsHash === currentToolHash
+            ? state.sameToolStreak + 1
+            : 1;
+        state.lastToolName = event.toolName;
+        state.lastToolParamsHash = currentToolHash;
+        if (classifyBroadScan(event.toolName, event.params))
+            state.broadScanCount += 1;
+        if (classifyBroadTest(event.toolName, event.params))
+            state.broadTestCount += 1;
+        const thresholdStop = this.checkThresholds(state);
+        if (thresholdStop) {
+            return this.makeStopResult(state, thresholdStop, event, ctx);
+        }
+        const candidates = [event.toolName];
+        const context = {
+            source: "openclaw-adapter.before_tool_call",
+            agent_id: ctx.agentId,
+            session_key: ctx.sessionKey,
+            session_id: ctx.sessionId,
+            run_id: event.runId ?? ctx.runId,
+            tool_name: event.toolName,
+            same_tool_streak: state.sameToolStreak,
+            duplicate_observation_streak: state.duplicateObservationStreak,
+            no_progress_streak: state.noProgressStreak,
+            broad_test_count: state.broadTestCount,
+            broad_scan_count: state.broadScanCount,
+            estimated_token_burn: state.estimatedTokenBurn,
+        };
+        if (this.client.rulesEvaluate) {
+            await this.client.rulesEvaluate({
+                scope: state.scope,
+                context,
+                candidates,
+            });
+        }
+        const decision = this.client.toolsSelect
+            ? await this.client.toolsSelect({
+                scope: state.scope,
+                runId: event.runId ?? ctx.runId ?? state.stateId,
+                context,
+                candidates,
+            })
+            : undefined;
+        this.captureDecision(state, decision ?? undefined);
+        if (decision?.selected_tool && decision.selected_tool !== event.toolName && this.config.strictToolBlocking) {
+            return {
+                block: true,
+                blockReason: `policy selected ${decision.selected_tool} instead of ${event.toolName}`,
+            };
+        }
+        return undefined;
+    }
+    async afterToolCall(event, ctx) {
+        const state = this.ensureState({
+            agentId: ctx.agentId,
+            sessionKey: ctx.sessionKey,
+            sessionId: ctx.sessionId,
+            runId: event.runId ?? ctx.runId,
+            workspaceDir: ctx.workspaceDir,
+        });
+        const summary = summarizeToolResult(event.result, event.error);
+        const observationHash = createHash("sha1").update(summary).digest("hex");
+        state.duplicateObservationStreak = state.lastObservationHash === observationHash
+            ? state.duplicateObservationStreak + 1
+            : 0;
+        state.lastObservationHash = observationHash;
+        const progress = inferProgress(event.toolName, summary);
+        state.noProgressStreak = progress ? 0 : state.noProgressStreak + 1;
+        state.estimatedLatencyBurnMs += Number(event.durationMs ?? 0);
+        state.estimatedTokenBurn += Math.max(1, Math.ceil(summary.length / 4));
+        if (this.client.toolsFeedback) {
+            await this.client.toolsFeedback({
+                scope: state.scope,
+                runId: event.runId ?? ctx.runId,
+                decisionId: state.lastDecisionId,
+                decisionUri: state.lastDecisionUri,
+                context: {
+                    source: "openclaw-adapter.after_tool_call",
+                    progress,
+                    duration_ms: event.durationMs ?? null,
+                    error: event.error ?? null,
+                },
+                candidates: [event.toolName],
+                selectedTool: event.toolName,
+                outcome: event.error ? "negative" : progress ? "positive" : "neutral",
+                note: progress ? "tool call made progress" : "tool call made no clear progress",
+                inputText: summary,
+            });
+        }
+        if (this.client.write) {
+            await this.client.write({
+                scope: state.scope,
+                inputText: `${event.toolName}: ${summary}`,
+                metadata: {
+                    source: "openclaw-adapter.after_tool_call",
+                    run_id: event.runId ?? ctx.runId,
+                    tool_call_id: event.toolCallId ?? ctx.toolCallId,
+                    duration_ms: event.durationMs ?? null,
+                },
+            });
+        }
+    }
+    async agentEnd(event, ctx) {
+        const state = this.findState({ sessionId: ctx.sessionId, sessionKey: ctx.sessionKey }) ?? this.ensureState({
+            agentId: ctx.agentId,
+            sessionKey: ctx.sessionKey,
+            sessionId: ctx.sessionId,
+            workspaceDir: ctx.workspaceDir,
+        });
+        if (!event.success && this.config.handoffFallbackEnabled && this.client.handoffStore && !state.handoffTriggered) {
+            state.handoffTriggered = true;
+            await this.client.handoffStore({
+                scope: state.scope,
+                anchor: `openclaw-loop-${state.stateId}`,
+                filePath: ctx.workspaceDir ?? "workspace",
+                summary: `OpenClaw run stopped: ${state.forcedStopReason ?? "agent_end_failure"}`,
+                handoffText: `Resume from degraded run. reason=${state.forcedStopReason ?? "agent_end_failure"}`,
+                repoRoot: ctx.workspaceDir ?? null,
+                handoffKind: "task_handoff",
+                title: "OpenClaw degraded run handoff",
+                risk: event.error ?? null,
+            });
+        }
+    }
+    decorateStopMessage(message, reason) {
+        if (!reason)
+            return message;
+        return {
+            ...message,
+            aionis_loop_control: {
+                reason,
+            },
+        };
+    }
+    ensureState(args) {
+        const stateId = args.runId ?? args.sessionId ?? args.sessionKey ?? randomUUID();
+        const existing = this.states.get(stateId);
+        if (existing)
+            return existing;
+        if (args.runId) {
+            const existingBySession = this.findState({ sessionId: args.sessionId, sessionKey: args.sessionKey });
+            if (existingBySession) {
+                existingBySession.runId = args.runId;
+                existingBySession.workspaceDir = args.workspaceDir ?? existingBySession.workspaceDir;
+                this.states.link(existingBySession, args.runId, args.sessionId, args.sessionKey);
+                return existingBySession;
+            }
+        }
+        const scope = this.config.scopeResolver(args);
+        const created = this.states.upsert(createRunState({
+            stateId,
+            scope,
+            agentId: args.agentId,
+            sessionKey: args.sessionKey,
+            sessionId: args.sessionId,
+            runId: args.runId,
+            workspaceDir: args.workspaceDir,
+            prompt: args.prompt,
+        }));
+        return this.states.link(created, args.runId, args.sessionId, args.sessionKey);
+    }
+    findState(args) {
+        if (args.sessionId) {
+            const bySession = this.states.get(args.sessionId);
+            if (bySession)
+                return bySession;
+        }
+        if (args.sessionKey) {
+            return this.states.get(args.sessionKey);
+        }
+        return undefined;
+    }
+    captureDecision(state, decision) {
+        if (!decision)
+            return;
+        state.lastDecisionId = decision.decision_id ?? state.lastDecisionId;
+        state.lastDecisionUri = decision.decision_uri ?? state.lastDecisionUri;
+        state.lastSelectedTool = decision.selected_tool ?? decision.selected ?? state.lastSelectedTool;
+    }
+    extractCandidateTools(messages) {
+        const out = new Set();
+        for (const message of messages ?? []) {
+            if (!message || typeof message !== "object")
+                continue;
+            const record = message;
+            const toolName = record.toolName ?? record.name;
+            if (typeof toolName === "string" && toolName.trim())
+                out.add(toolName.trim());
+        }
+        return [...out];
+    }
+    resolveReplayHint(state, event, ctx) {
+        return this.config.replayHintResolver?.({
+            agentId: ctx.agentId,
+            sessionKey: ctx.sessionKey,
+            sessionId: ctx.sessionId,
+            runId: event.runId ?? ctx.runId,
+            workspaceDir: ctx.workspaceDir,
+            toolName: event.toolName,
+            toolParams: event.params,
+        }) ?? undefined;
+    }
+    checkThresholds(state) {
+        const t = this.config.thresholds;
+        if (state.stepCount > t.maxSteps)
+            return "max_steps_exceeded";
+        if (state.sameToolStreak > t.maxSameToolStreak)
+            return "same_tool_streak_exceeded";
+        if (state.duplicateObservationStreak > t.maxDuplicateObservationStreak)
+            return "duplicate_observation_exceeded";
+        if (state.noProgressStreak > t.maxNoProgressStreak)
+            return "no_progress_exceeded";
+        if (state.estimatedTokenBurn > t.maxEstimatedTokenBurn)
+            return "budget_exceeded";
+        if (state.broadTestCount > t.maxBroadTestInvocations)
+            return "policy_denied_only_path";
+        if (state.broadScanCount > t.maxBroadScanInvocations)
+            return "policy_denied_only_path";
+        return undefined;
+    }
+    async makeStopResult(state, reason, event, ctx) {
+        state.forcedStopReason = reason;
+        const replayHint = this.resolveReplayHint(state, event, ctx);
+        if (replayHint && this.config.replayDispatchEnabled && this.client.replayPlaybookCandidate && this.client.replayPlaybookDispatch && !state.replayDispatchAttempted) {
+            state.replayDispatchAttempted = true;
+            const candidateResult = await this.client.replayPlaybookCandidate({
+                scope: state.scope,
+                playbookId: replayHint.playbookId,
+                version: replayHint.version,
+                deterministicGate: replayHint.deterministicGate,
+            });
+            if (candidateResult?.candidate?.eligible_for_deterministic_replay) {
+                await this.client.replayPlaybookDispatch({
+                    scope: state.scope,
+                    playbookId: replayHint.playbookId,
+                    version: replayHint.version,
+                    params: {
+                        source: "openclaw-adapter.loop-control",
+                        reason,
+                        ...(replayHint.params ?? {}),
+                    },
+                    mode: replayHint.mode ?? candidateResult.candidate.recommended_mode,
+                    maxSteps: replayHint.maxSteps,
+                    deterministicGate: replayHint.deterministicGate,
+                });
+                state.forcedStopReason = "replay_dispatch_selected";
+                return { block: true, blockReason: "replay dispatch selected" };
+            }
+        }
+        if (this.config.handoffFallbackEnabled && this.client.handoffStore && !state.handoffTriggered) {
+            state.handoffTriggered = true;
+            await this.client.handoffStore({
+                scope: state.scope,
+                anchor: `openclaw-loop-${state.stateId}`,
+                filePath: ctx.workspaceDir ?? "workspace",
+                summary: `Forced loop stop: ${reason}`,
+                handoffText: `The run was stopped before ${event.toolName}. reason=${reason}. Resume from current workspace state with a narrower tool path.`,
+                repoRoot: ctx.workspaceDir ?? null,
+                handoffKind: "task_handoff",
+                title: "OpenClaw loop-control handoff",
+            });
+            state.forcedStopReason = "handoff_store_selected";
+            return { block: true, blockReason: "handoff stored after loop-control stop" };
+        }
+        return { block: true, blockReason: reason };
+    }
+}

package/dist/adapter/state.d.ts

@@ -0,0 +1,47 @@
+import type { LoopStopReasonCode } from "../types/config.js";
+export type LoopRunState = {
+    stateId: string;
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    runId?: string;
+    workspaceDir?: string;
+    scope: string;
+    promptHash?: string;
+    stepCount: number;
+    sameToolStreak: number;
+    duplicateObservationStreak: number;
+    noProgressStreak: number;
+    broadTestCount: number;
+    broadScanCount: number;
+    estimatedTokenBurn: number;
+    estimatedLatencyBurnMs: number;
+    lastToolName?: string;
+    lastToolParamsHash?: string;
+    lastObservationHash?: string;
+    lastDecisionId?: string;
+    lastDecisionUri?: string;
+    lastSelectedTool?: string;
+    forcedStopReason?: LoopStopReasonCode;
+    handoffTriggered: boolean;
+    replayDispatchAttempted: boolean;
+};
+export declare function hashStable(value: unknown): string;
+export declare function createRunState(args: {
+    stateId: string;
+    scope: string;
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    runId?: string;
+    workspaceDir?: string;
+    prompt?: string;
+}): LoopRunState;
+export declare class LoopStateStore {
+    private readonly states;
+    get(stateId: string): LoopRunState | undefined;
+    upsert(state: LoopRunState): LoopRunState;
+    link(state: LoopRunState, ...ids: Array<string | undefined>): LoopRunState;
+    delete(stateId: string): void;
+    deleteAllFor(target: LoopRunState): void;
+}

package/dist/adapter/state.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+export function hashStable(value) {
+    return createHash("sha1").update(JSON.stringify(value ?? null)).digest("hex");
+}
+export function createRunState(args) {
+    return {
+        stateId: args.stateId,
+        agentId: args.agentId,
+        sessionKey: args.sessionKey,
+        sessionId: args.sessionId,
+        runId: args.runId,
+        workspaceDir: args.workspaceDir,
+        scope: args.scope,
+        promptHash: args.prompt ? hashStable(args.prompt) : undefined,
+        stepCount: 0,
+        sameToolStreak: 0,
+        duplicateObservationStreak: 0,
+        noProgressStreak: 0,
+        broadTestCount: 0,
+        broadScanCount: 0,
+        estimatedTokenBurn: 0,
+        estimatedLatencyBurnMs: 0,
+        handoffTriggered: false,
+        replayDispatchAttempted: false,
+    };
+}
+export class LoopStateStore {
+    states = new Map();
+    get(stateId) {
+        return this.states.get(stateId);
+    }
+    upsert(state) {
+        this.states.set(state.stateId, state);
+        return state;
+    }
+    link(state, ...ids) {
+        for (const id of ids) {
+            if (!id)
+                continue;
+            this.states.set(id, state);
+        }
+        return state;
+    }
+    delete(stateId) {
+        this.states.delete(stateId);
+    }
+    deleteAllFor(target) {
+        for (const [key, value] of this.states.entries()) {
+            if (value === target)
+                this.states.delete(key);
+        }
+    }
+}

package/dist/binding/openclaw-hook-binding.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawHostApi } from "../types/openclaw.js";
+import { AionisLoopControlAdapter } from "../adapter/loop-control-adapter.js";
+export declare function attachToOpenClawHost(api: OpenClawHostApi, adapter: AionisLoopControlAdapter): void;

package/dist/binding/openclaw-hook-binding.js

@@ -0,0 +1,36 @@
+export function attachToOpenClawHost(api, adapter) {
+    if (typeof api.on !== "function") {
+        api.logger.warn("openclaw-aionis-adapter: host hook API unavailable; binding skipped");
+        return;
+    }
+    api.on("session_start", async (event, ctx) => {
+        adapter.sessionStart({ ...ctx, sessionId: event.sessionId });
+    });
+    api.on("session_end", async (event) => {
+        adapter.sessionEnd(event.sessionId);
+    });
+    api.on("before_agent_start", async (event, ctx) => {
+        return adapter.beforeAgentStart(event, ctx);
+    });
+    api.on("before_tool_call", async (event, ctx) => {
+        return adapter.beforeToolCall(event, ctx);
+    });
+    api.on("after_tool_call", async (event, ctx) => {
+        await adapter.afterToolCall(event, ctx);
+    });
+    api.on("agent_end", async (event, ctx) => {
+        await adapter.agentEnd(event, ctx);
+    });
+    api.on("tool_result_persist", async (event) => {
+        const reason = typeof event.message?.aionis_loop_control === "object"
+            ? event.message.aionis_loop_control.reason
+            : undefined;
+        return { message: adapter.decorateStopMessage(event.message, reason) };
+    });
+    api.on("before_message_write", async (event) => {
+        const reason = typeof event.message?.aionis_loop_control === "object"
+            ? event.message.aionis_loop_control.reason
+            : undefined;
+        return { message: adapter.decorateStopMessage(event.message, reason) };
+    });
+}

package/dist/client/aionis-http-client.d.ts

@@ -0,0 +1,108 @@
+import type { AionisHttpClientOptions, AionisLoopControlClient, AionisToolDecision } from "../types/aionis.js";
+export declare class AionisHttpClientError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status: number, code?: string | undefined, details?: unknown | undefined);
+}
+export declare class AionisHttpLoopControlClient implements AionisLoopControlClient {
+    private readonly options;
+    constructor(options: AionisHttpClientOptions);
+    private post;
+    private withIdentity;
+    contextAssemble(args: {
+        scope: string;
+        queryText: string;
+        context: Record<string, unknown>;
+        toolCandidates?: string[];
+    }): Promise<{
+        layered_context?: {
+            merged_text?: string;
+        };
+        tools?: AionisToolDecision;
+    } | null>;
+    rulesEvaluate(args: {
+        scope: string;
+        context: Record<string, unknown>;
+        candidates: string[];
+    }): Promise<Record<string, unknown> | null>;
+    toolsSelect(args: {
+        scope: string;
+        runId: string;
+        context: Record<string, unknown>;
+        candidates: string[];
+    }): Promise<AionisToolDecision | null>;
+    toolsDecision(args: {
+        scope: string;
+        decisionId?: string;
+        decisionUri?: string;
+        runId?: string;
+    }): Promise<Record<string, unknown> | null>;
+    toolsFeedback(args: {
+        scope: string;
+        runId?: string;
+        decisionId?: string;
+        decisionUri?: string;
+        context: Record<string, unknown>;
+        candidates: string[];
+        selectedTool: string;
+        outcome: "positive" | "negative" | "neutral";
+        note?: string;
+        inputText: string;
+    }): Promise<Record<string, unknown> | null>;
+    write(args: {
+        scope: string;
+        inputText: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | null>;
+    handoffStore(args: {
+        scope: string;
+        anchor: string;
+        filePath: string;
+        summary: string;
+        handoffText: string;
+        repoRoot?: string | null;
+        symbol?: string | null;
+        handoffKind?: "patch_handoff" | "review_handoff" | "task_handoff";
+        title?: string | null;
+        risk?: string | null;
+        acceptanceChecks?: string[];
+        tags?: string[];
+        targetFiles?: string[];
+        nextAction?: string | null;
+        mustChange?: string[];
+        mustRemove?: string[];
+        mustKeep?: string[];
+    }): Promise<Record<string, unknown> | null>;
+    replayPlaybookCandidate(args: {
+        scope: string;
+        playbookId: string;
+        version?: number;
+        deterministicGate?: Record<string, unknown>;
+    }): Promise<{
+        playbook?: {
+            playbook_id?: string;
+            version?: number;
+            status?: string;
+            name?: string | null;
+            uri?: string;
+        };
+        candidate?: {
+            eligible_for_deterministic_replay?: boolean;
+            recommended_mode?: "simulate" | "strict" | "guided";
+            next_action?: string;
+            mismatch_reasons?: string[];
+        };
+        cost_signals?: Record<string, unknown>;
+    } | null>;
+    replayPlaybookDispatch(args: {
+        scope: string;
+        playbookId: string;
+        version?: number;
+        params?: Record<string, unknown>;
+        mode?: "simulate" | "strict" | "guided";
+        maxSteps?: number;
+        deterministicGate?: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | null>;
+}
+export declare function createAionisHttpLoopControlClient(options: AionisHttpClientOptions): AionisLoopControlClient;