@alignfirst/service-openclaw-plugin 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas MUR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# @alignfirst/service-openclaw-plugin
+
+The OpenClaw gateway plugin of the [AlignFirst Dev Kit](https://alignfirst.paroi.tech/openclaw-dev-kit). It currently provides thread handoff: after a native message action delivers its visible starter, the plugin starts the regular channel-thread session through a reply run it dispatches itself. Delivery evidence and pending handoffs survive gateway restart in a plugin-owned SQLite database.
+
+## Install and enable
+
+Install the package through OpenClaw's normal external-plugin procedure, enable plugin ID
+`alignfirst-service`, and explicitly allow the optional `thread_handoff` tool:
+
+```json
+{
+  "plugins": {
+    "allow": ["alignfirst-service"],
+    "entries": { "alignfirst-service": { "enabled": true } }
+  },
+  "tools": { "allow": ["thread_handoff"] }
+}
+```
+
+The built-in channel mapping is Slack and Discord. Synthetic or renamed channel plugins can map
+their IDs to the corresponding native contract:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "alignfirst-service": {
+        "enabled": true,
+        "config": {
+          "channelSurfaces": {
+            "slack-mock": "slack",
+            "discord-mock": "discord"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Thread handoff contract
+
+The plugin observes successful native `message` actions but never creates a thread itself.
+
+- Slack evidence is a `send` to the current parent channel with an explicit `threadId`, nonempty body, `deliveryStatus: "sent"`, and `messageDelivery: { status: "settled", partialDelivery: false }`. The result must include a channel-kind `target` naming the parent and a nonempty `messageId`; `result.receipt.threadId`, when present, must match the requested thread. The plugin-path `{ ok, result }` shape used by team-qualified Slack sends is rejected.
+- Discord evidence is a successful anchored `thread-create` in the current parent channel with a
+  nonempty starter and returned thread ID. A partial result is rejected.
+- `thread_handoff { "action": "start", "threadId": "..." }` returns `queued` or
+  `alreadyStarted`, plus the opaque handoff ID and canonical target session key.
+
+The claim result has this contract:
+
+| Status | Meaning |
+| --- | --- |
+| `claimed` | The first claim, or a repeated claim by the same run. |
+| `alreadyClaimed` | Another run owns the handoff. The result includes `claimedAt`. |
+| `none` | No handoff matches an ordinary human turn in the target thread. |
+
+The receiving turn calls `thread_handoff { "action": "claim" }` once before task effects. The tool resolves the handoff from the current thread session; an explicit handoff ID remains an optional API parameter.
+
+Inputs are strict. Errors begin with a stable reason code: `unsupportedContext`,
+`unverifiedThreadDelivery`, `conflictingHandoff`, `invalidTarget`, or
+`unavailablePersistentState`. A capacity failure preserves `STORE_LIMIT_EXCEEDED` as its cause.
+Rejected eligible delivery observations emit one debug line with `notSent`, `partialDelivery`, `channelMismatch`, `threadMismatch`, `missingMessageId`, `missingThread`, `missingStarter`, or `accountMismatch`. The line contains no starter text or result payload.
+
+Starts are limited to distinct regular parent-channel sessions. DMs, group DMs, Slack Agent View,
+ACP, subagent, cron, global/shared, already-threaded, and ambiguous cross-account routes are not
+supported.
+
+## Turn start and persistence
+
+The plugin commits a pending record before dispatching `Take over this thread.` from `AlignFirst Service` as a reply run through the channel-inbound path. Immediate dispatch starts outside the calling tool turn's asynchronous context. Its plugin-built context sets the service display name without a human sender ID or command authority, and sets `WasMentioned: false`. These plugin-dispatched turns disable block streaming so their complete final payload reaches OpenClaw's durable outbound path. The reply run records the session's last route. The plugin's in-process nudge does not need an `openclaw` executable on the gateway's `PATH`.
+
+The message body is static: it carries no starter copy, routing fields, or handoff ID. The playbook routes by thread metadata, claims the current session, and reads the visible starter and human replies through thread history. The nudge supplies no missing input or approval. A takeover turn with nothing to report ends with `HEARTBEAT_OK`; the deterministic gateway probe confirmed that `NO_REPLY` still triggers isolated finalization on this path.
+
+The plugin starts the thread session and does nothing after that. Alcode completion uses OpenClaw's own completion path.
+
+Each takeover turn gets the regular agent budget from `agents.defaults.timeoutSeconds`, including the 48-hour OpenClaw default and the unlimited `0` value.
+
+The database is `<stateDir>/thread-handoff/state.sqlite`, where `stateDir` comes from
+`api.runtime.state.resolveStateDir()`. It uses WAL, full synchronous durability, a `0700` directory,
+and a `0600` database file. Receipts expire after one hour and are capped at 10,000 active entries.
+Handoffs have a separate 10,000-record cap and do not expire automatically. The plugin scans
+pending records at startup and every 30 seconds. It starts at most ten attempts, with at least 60
+seconds after an attempt ends before the next one. A record still pending after the tenth attempt
+stays claimable by the next human message in the thread. Claimed records remain as duplicate-start
+protection; native OpenClaw recovery owns interrupted work after claim.
+
+Use `openclaw thread-handoff list [--json]` to inspect handoffs with their attempt counts and
+claimer identity. Use `openclaw thread-handoff receipts [--json]` to inspect active delivery
+receipts without starter text. `openclaw thread-handoff retire <handoff-id>` removes a claimed
+record; add `--force` for a pending record, typically a parked one.
+
+Opening a database created by plugin 0.2.0 migrates it automatically to schema 2. The migration
+preserves pending attempt history and claimed records. To downgrade to 0.2.0, stop the gateway and delete `<stateDir>/thread-handoff/state.sqlite`. Deletion loses pending handoffs.
+
+For a backup, stop the gateway and let the plugin close/checkpoint its connection, then copy the
+database together with any WAL/SHM crash-state files; alternatively use a SQLite-consistent backup.
+Do not copy only the main file from a live gateway. Retain pending work. Retire only finished managed
+handoffs, because deleting a claimed record also deletes its duplicate-start protection.
+
+## Development
+
+`src/index.ts` defines the plugin identity and configuration schema. `src/thread-handoff/` owns handoff registration, tools, hooks, recovery and persistence. Additional assistant features can register alongside it through the root entry point.
+
+```bash
+npm run build --workspace @alignfirst/service-openclaw-plugin
+npm test --workspace @alignfirst/service-openclaw-plugin
+npm run typecheck --workspace @alignfirst/service-openclaw-plugin
+npm run lint --workspace @alignfirst/service-openclaw-plugin
+```
+
+The ordinary test command excludes the real-gateway suite. To exercise the package as an external
+plugin against the pinned OpenClaw 2026.9.4 runtime, including Slack/Discord delivery, concurrent human messages, duplicate starts, same-session continuation, and abrupt restart recovery:
+
+```bash
+KEEP_THREAD_HANDOFF_ARTIFACTS=1 npm run test:integration --workspace @alignfirst/service-openclaw-plugin
+```
+
+Retained fixtures are written under `/tmp/thread-handoff-*` with gateway logs, provider requests,
+plugin SQLite state, configuration, and workspace files. Omit the environment variable for normal
+automatic cleanup.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+declare const _default: Omit<{
+    id: string;
+    name: string;
+    description: string;
+    kind?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["kind"];
+    configSchema?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema | (() => import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema);
+    reload?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["reload"];
+    nodeHostCommands?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["nodeHostCommands"];
+    securityAuditCollectors?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["securityAuditCollectors"];
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+}, "configSchema"> & {
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,20 @@
+import { buildJsonPluginConfigSchema, definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { DEFAULT_CHANNEL_SURFACES, registerThreadHandoff } from "./thread-handoff/index.js";
+const configSchema = buildJsonPluginConfigSchema({
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        channelSurfaces: {
+            type: "object",
+            additionalProperties: { enum: ["slack", "discord"] },
+            default: DEFAULT_CHANNEL_SURFACES,
+        },
+    },
+});
+export default definePluginEntry({
+    id: "alignfirst-service",
+    name: "AlignFirst Service",
+    description: "OpenClaw capabilities for the AlignFirst Dev Kit.",
+    configSchema,
+    register: registerThreadHandoff,
+});

package/dist/thread-handoff/cli.d.ts

@@ -0,0 +1,5 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { DeliveryReceipt, HandoffRecord } from "./types.js";
+export declare function registerThreadHandoffCli(api: OpenClawPluginApi): void;
+export declare function renderHandoffs(records: HandoffRecord[], json: boolean): string;
+export declare function renderReceipts(receipts: DeliveryReceipt[], json: boolean): string;

package/dist/thread-handoff/cli.js

@@ -0,0 +1,89 @@
+import { createHandoffStore } from "./state.js";
+export function registerThreadHandoffCli(api) {
+    api.registerCli(({ program }) => {
+        const command = program
+            .command("thread-handoff")
+            .description("Inspect and maintain durable thread handoffs");
+        command
+            .command("list")
+            .description("List pending and claimed handoffs")
+            .option("--json", "Print JSON")
+            .action((options) => listHandoffs(api, options.json === true));
+        command
+            .command("receipts")
+            .description("List active delivery receipts")
+            .option("--json", "Print JSON")
+            .action((options) => listReceipts(api, options.json === true));
+        command
+            .command("retire")
+            .description("Retire one claimed handoff")
+            .argument("<handoff-id>")
+            .option("--force", "Also retire a pending handoff")
+            .action((handoffId, options) => retireHandoff(api, handoffId, options.force === true));
+    }, {
+        descriptors: [
+            {
+                name: "thread-handoff",
+                description: "Inspect and maintain durable thread handoffs",
+                hasSubcommands: true,
+                machineOutput: ({ argv }) => argv.includes("--json"),
+            },
+        ],
+    });
+}
+function listHandoffs(api, json) {
+    withStore(api, (store) => {
+        process.stdout.write(`${renderHandoffs(store.listHandoffs(), json)}\n`);
+    });
+}
+export function renderHandoffs(records, json) {
+    if (json) {
+        const projected = records.map(({ starterText: _starterText, ...record }) => record);
+        return JSON.stringify(projected, null, 2);
+    }
+    if (records.length === 0)
+        return "No managed handoffs.";
+    return records
+        .map((record) => `${record.handoffId}\t${record.state}\t${record.attemptCount} attempts\t${record.targetSessionKey}\t${record.createdAt}`)
+        .join("\n");
+}
+function withStore(api, operation) {
+    const store = createHandoffStore(api.runtime.state.resolveStateDir());
+    try {
+        return operation(store);
+    }
+    finally {
+        store.close();
+    }
+}
+function listReceipts(api, json) {
+    withStore(api, (store) => {
+        process.stdout.write(`${renderReceipts(store.listReceipts(Date.now()), json)}\n`);
+    });
+}
+export function renderReceipts(receipts, json) {
+    if (json) {
+        const projected = receipts.map((receipt) => ({
+            sessionKey: receipt.sessionKey,
+            sessionId: receipt.sessionId,
+            threadId: receipt.threadId,
+            ...(receipt.starterMessageId ? { starterMessageId: receipt.starterMessageId } : {}),
+            createdAt: receipt.createdAt,
+            expiresAt: receipt.expiresAt,
+        }));
+        return JSON.stringify(projected, null, 2);
+    }
+    if (receipts.length === 0)
+        return "No active receipts.";
+    return receipts
+        .map((receipt) => `${receipt.sessionKey}\t${receipt.threadId}\t${receipt.starterMessageId ?? "-"}\t${receipt.createdAt}\t${receipt.expiresAt}`)
+        .join("\n");
+}
+function retireHandoff(api, handoffId, force) {
+    withStore(api, (store) => {
+        const retired = store.retireHandoff(handoffId.trim(), { force });
+        if (!retired)
+            throw new Error(`Unknown handoff: ${handoffId}`);
+        process.stdout.write(`Retired ${handoffId}.\n`);
+    });
+}

package/dist/thread-handoff/dispatch.d.ts

@@ -0,0 +1,15 @@
+import type { OpenClawPluginApi, PluginLogger } from "openclaw/plugin-sdk/plugin-entry";
+import type { TurnRequest } from "./types.js";
+export declare function dispatchTurn(params: {
+    runtime: OpenClawPluginApi["runtime"];
+    logger: PluginLogger;
+    request: TurnRequest;
+}): Promise<void>;
+export declare function buildTurnContext(request: TurnRequest): Record<string, unknown>;
+export declare function buildLastRoute(request: TurnRequest): {
+    sessionKey: string;
+    channel: string;
+    to: string;
+    accountId?: string;
+    threadId?: string;
+};

package/dist/thread-handoff/dispatch.js

@@ -0,0 +1,75 @@
+import { readConversationId } from "./routing.js";
+import { errorMessage } from "./values.js";
+export async function dispatchTurn(params) {
+    const { runtime, logger, request } = params;
+    const cfg = runtime.config.current();
+    await runtime.channel.inbound.dispatchReply({
+        // The dispatcher only reads configuration, while the runtime exposes it as readonly.
+        cfg: cfg,
+        channel: request.channelId,
+        ...(request.route.accountId ? { accountId: request.route.accountId } : {}),
+        agentId: request.agentId,
+        routeSessionKey: request.sessionKey,
+        storePath: runtime.channel.session.resolveStorePath(cfg.session?.store, {
+            agentId: request.agentId,
+        }),
+        ctxPayload: runtime.channel.reply.finalizeInboundContext(buildTurnContext(request)),
+        recordInboundSession: runtime.channel.session.recordInboundSession,
+        dispatchReplyWithBufferedBlockDispatcher: runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
+        delivery: {
+            // Owning the key prevents core from falling back to the context thread on Discord.
+            durable: { to: request.route.to, threadId: request.route.threadId, replyToId: null },
+            deliver: async () => ({ visibleReplySent: false }),
+            onError: (error, info) => logger.warn(`thread-handoff delivery failed (${info.kind}): ${errorMessage(error)}`),
+        },
+        replyPipeline: {},
+        replyOptions: { disableBlockStreaming: true },
+        record: {
+            updateLastRoute: buildLastRoute(request),
+            onRecordError: (error) => logger.warn(`thread-handoff session record failed: ${errorMessage(error)}`),
+        },
+    });
+}
+export function buildTurnContext(request) {
+    const conversationId = readConversationId(request.route.to);
+    if (!conversationId)
+        throw new Error(`Invalid delivery target: ${request.route.to}`);
+    const messageThreadId = request.surface === "slack" ? request.route.threadId : conversationId;
+    return {
+        Body: request.message,
+        BodyForAgent: request.message,
+        RawBody: request.message,
+        CommandBody: "",
+        CommandInterpretationSuppressed: true,
+        CommandAuthorized: false,
+        SessionKey: request.sessionKey,
+        AccountId: request.route.accountId,
+        Provider: request.channelId,
+        Surface: request.channelId,
+        OriginatingChannel: request.channelId,
+        From: request.route.to,
+        To: request.route.to,
+        OriginatingTo: request.route.to,
+        NativeChannelId: request.surface === "slack" ? request.parentConversationId : conversationId,
+        ChatType: "group",
+        GroupChannel: request.parentConversationId,
+        ConversationLabel: request.parentConversationId,
+        GroupSubject: request.parentConversationId,
+        MessageThreadId: messageThreadId,
+        ThreadParentId: request.parentConversationId,
+        WasMentioned: false,
+        SenderName: "AlignFirst Service",
+        MessageSid: request.messageId,
+        MessageSidFull: request.messageId,
+        Timestamp: Date.now(),
+    };
+}
+export function buildLastRoute(request) {
+    return {
+        sessionKey: request.sessionKey,
+        channel: request.route.channel,
+        to: request.route.to,
+        ...(request.route.accountId ? { accountId: request.route.accountId } : {}),
+        ...(request.route.threadId ? { threadId: request.route.threadId } : {}),
+    };
+}

package/dist/thread-handoff/errors.d.ts

@@ -0,0 +1,6 @@
+import type { HandoffErrorCode } from "./types.js";
+export declare class HandoffError extends Error {
+    readonly code: HandoffErrorCode;
+    readonly causeCode?: string;
+    constructor(code: HandoffErrorCode, message: string, cause?: unknown);
+}

package/dist/thread-handoff/errors.js

@@ -0,0 +1,16 @@
+export class HandoffError extends Error {
+    code;
+    causeCode;
+    constructor(code, message, cause) {
+        super(message, { cause });
+        this.name = "HandoffError";
+        this.code = code;
+        this.causeCode = readCauseCode(cause);
+    }
+}
+function readCauseCode(cause) {
+    if (!cause || typeof cause !== "object" || Array.isArray(cause))
+        return;
+    const code = Reflect.get(cause, "code");
+    return typeof code === "string" ? code : undefined;
+}

package/dist/thread-handoff/index.d.ts

@@ -0,0 +1,4 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { PluginConfiguration } from "./types.js";
+export declare const DEFAULT_CHANNEL_SURFACES: PluginConfiguration["channelSurfaces"];
+export declare function registerThreadHandoff(api: OpenClawPluginApi): void;

package/dist/thread-handoff/index.js

@@ -0,0 +1,70 @@
+import { registerThreadHandoffCli } from "./cli.js";
+import { createReceiptCoordinator } from "./receipts.js";
+import { createRunIdCache } from "./run-ids.js";
+import { createHandoffService } from "./service.js";
+import { createHandoffStore, resolveDatabasePath } from "./state.js";
+import { createThreadHandoffTool } from "./tool.js";
+import { asRecord } from "./values.js";
+export const DEFAULT_CHANNEL_SURFACES = {
+    slack: "slack",
+    discord: "discord",
+};
+export function registerThreadHandoff(api) {
+    const configuration = readConfiguration(api.pluginConfig);
+    let store;
+    const getStore = () => {
+        store ??= createHandoffStore(api.runtime.state.resolveStateDir());
+        return store;
+    };
+    const receipts = createReceiptCoordinator({ configuration, getStore, logger: api.logger });
+    const runIds = createRunIdCache();
+    const service = createHandoffService({
+        runtime: api.runtime,
+        configuration,
+        getStore,
+        logger: api.logger,
+    });
+    api.registerTool((context) => createThreadHandoffTool({ context, configuration, receipts, runIds, getStore, service }), { name: "thread_handoff", optional: true });
+    api.on("after_tool_call", (event, context) => {
+        receipts.observe({
+            toolName: event.toolName,
+            params: asRecord(event.params) ?? {},
+            ...(event.toolCallId ? { toolCallId: event.toolCallId } : {}),
+            ...(event.result !== undefined ? { result: event.result } : {}),
+            ...(event.error ? { error: event.error } : {}),
+        }, context);
+    });
+    api.on("before_tool_call", (event, context) => {
+        if (event.toolName === "thread_handoff")
+            runIds.remember(context);
+    });
+    registerThreadHandoffCli(api);
+    if (api.registrationMode !== "full")
+        return;
+    api.registerService({
+        id: "thread-handoff-recovery",
+        async start() {
+            await service.start();
+            api.logger.info(`thread-handoff persistence ready at ${resolveDatabasePath(api.runtime.state.resolveStateDir())}`);
+        },
+        async stop() {
+            // `service.stop()` guarantees no detached completion calls `getStore()` afterwards; such a
+            // call would reopen the database behind the close below.
+            await service.stop();
+            store?.close();
+            store = undefined;
+        },
+    });
+}
+function readConfiguration(value) {
+    const record = asRecord(value);
+    const configured = asRecord(record?.channelSurfaces);
+    const channelSurfaces = {};
+    for (const [channel, surface] of Object.entries(configured ?? DEFAULT_CHANNEL_SURFACES)) {
+        if (surface !== "slack" && surface !== "discord") {
+            throw new Error(`Invalid thread-handoff surface for channel ${channel}.`);
+        }
+        channelSurfaces[channel] = surface;
+    }
+    return { channelSurfaces };
+}

package/dist/thread-handoff/receipts.d.ts

@@ -0,0 +1,26 @@
+import type { OpenClawPluginToolContext, PluginLogger } from "openclaw/plugin-sdk/plugin-entry";
+import type { HandoffStore } from "./state.js";
+import type { DeliveryReceipt, PluginConfiguration, ReceiptIdentity } from "./types.js";
+export interface ReceiptCoordinator {
+    captureContext(context: OpenClawPluginToolContext): void;
+    observe(event: ToolObservation, context: HookContext): void;
+    waitForReceipt(identity: ReceiptIdentity): Promise<DeliveryReceipt | undefined>;
+}
+interface ToolObservation {
+    toolName: string;
+    params: Record<string, unknown>;
+    toolCallId?: string;
+    result?: unknown;
+    error?: string;
+}
+interface HookContext {
+    sessionKey?: string;
+    sessionId?: string;
+}
+export declare function createReceiptCoordinator(params: {
+    configuration: PluginConfiguration;
+    getStore: () => HandoffStore;
+    logger: PluginLogger;
+    now?: () => number;
+}): ReceiptCoordinator;
+export {};