@alignfirst/service-openclaw-plugin 0.3.1

package/dist/thread-handoff/state.js

@@ -0,0 +1,379 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { HandoffError } from "./errors.js";
+import { errorMessage } from "./values.js";
+const DATABASE_DIRECTORY_MODE = 0o700;
+const DATABASE_FILE_MODE = 0o600;
+const SCHEMA_VERSION = 2;
+const STORE_CAPACITY = 10_000;
+export function createHandoffStore(stateDir) {
+    const database = openDatabase(resolveDatabasePath(stateDir));
+    return createStoreOperations(database);
+}
+export function resolveDatabasePath(stateDir) {
+    return join(stateDir, "thread-handoff", "state.sqlite");
+}
+function openDatabase(databasePath) {
+    const directoryPath = dirname(databasePath);
+    mkdirSync(directoryPath, { recursive: true, mode: DATABASE_DIRECTORY_MODE });
+    chmodSync(directoryPath, DATABASE_DIRECTORY_MODE);
+    let database;
+    try {
+        database = new DatabaseSync(databasePath);
+        database.exec("PRAGMA busy_timeout = 2000;");
+        database.exec("PRAGMA journal_mode = WAL;");
+        database.exec("PRAGMA synchronous = FULL;");
+        initializeSchema(database);
+        chmodSync(databasePath, DATABASE_FILE_MODE);
+        return database;
+    }
+    catch (error) {
+        database?.close();
+        throw persistentStateError(`Could not open the thread-handoff database: ${errorMessage(error)}`, error);
+    }
+}
+function initializeSchema(database) {
+    const row = database.prepare("PRAGMA user_version").get();
+    if (row.user_version === SCHEMA_VERSION)
+        return;
+    if (row.user_version === 1) {
+        migrateSchema1(database);
+        return;
+    }
+    if (row.user_version !== 0) {
+        throw new Error(`Unsupported thread-handoff database schema ${row.user_version}.`);
+    }
+    inTransaction(database, () => {
+        database.exec(`
+      CREATE TABLE receipts (
+        receipt_key TEXT PRIMARY KEY,
+        source_session_key TEXT NOT NULL,
+        source_session_id TEXT NOT NULL,
+        thread_id TEXT NOT NULL,
+        expires_at INTEGER NOT NULL,
+        record_json TEXT NOT NULL
+      ) STRICT;
+      CREATE INDEX receipts_lookup_idx
+        ON receipts (source_session_key, source_session_id, thread_id, expires_at);
+      CREATE INDEX receipts_expiry_idx ON receipts (expires_at);
+      CREATE TABLE handoffs (
+        route_key TEXT PRIMARY KEY,
+        target_session_key TEXT NOT NULL UNIQUE,
+        handoff_id TEXT NOT NULL UNIQUE,
+        state TEXT NOT NULL CHECK (state IN ('pending', 'claimed')),
+        attempt_count INTEGER NOT NULL DEFAULT 0,
+        last_attempted_at INTEGER,
+        record_json TEXT NOT NULL
+      ) STRICT;
+      CREATE INDEX handoffs_pending_idx ON handoffs (state, attempt_count, last_attempted_at);
+      PRAGMA user_version = 2;
+    `);
+    });
+}
+function migrateSchema1(database) {
+    inTransaction(database, () => {
+        database.exec("ALTER TABLE handoffs RENAME COLUMN enqueue_count TO attempt_count;");
+        database.exec("ALTER TABLE handoffs RENAME COLUMN last_enqueued_at TO last_attempted_at;");
+        const rows = database
+            .prepare("SELECT route_key, record_json FROM handoffs")
+            .all();
+        const update = database.prepare("UPDATE handoffs SET record_json = ? WHERE route_key = ?");
+        for (const row of rows) {
+            const record = parseRecord(row.record_json, "handoff");
+            const { enqueueCount, lastEnqueuedAt, ...rest } = record;
+            update.run(JSON.stringify({
+                ...rest,
+                schemaVersion: 2,
+                attemptCount: enqueueCount,
+                ...(lastEnqueuedAt !== undefined ? { lastAttemptedAt: lastEnqueuedAt } : {}),
+            }), row.route_key);
+        }
+        database.exec("PRAGMA user_version = 2;");
+    });
+}
+function createStoreOperations(database) {
+    return {
+        insertReceipt: (receipt, now) => insertReceipt(database, receipt, now),
+        findReceipt: (identity, now) => findReceipt(database, identity, now),
+        listReceipts: (now) => listReceipts(database, now),
+        findHandoffByRoute: (routeKey) => findHandoffByRoute(database, routeKey),
+        insertHandoff: (record) => insertHandoff(database, record),
+        claimHandoff: (identity, now) => claimHandoff(database, identity, now),
+        recordAttempt: (routeKey, startedAt) => recordAttempt(database, routeKey, startedAt),
+        recordAttemptEnd: (routeKey, endedAt) => recordAttemptEnd(database, routeKey, endedAt),
+        listPending: (query) => listPending(database, query),
+        listHandoffs: () => listHandoffs(database),
+        retireHandoff: (handoffId, options) => retireHandoff(database, handoffId, options),
+        close: () => database.close(),
+    };
+}
+function insertReceipt(database, receipt, now) {
+    runStateOperation("store a delivery receipt", () => inTransaction(database, () => {
+        database.prepare("DELETE FROM receipts WHERE expires_at <= ?").run(now);
+        const existing = database
+            .prepare("SELECT receipt_key FROM receipts WHERE receipt_key = ?")
+            .get(receipt.receiptKey);
+        if (!existing)
+            assertCapacity(database, "receipts");
+        database
+            .prepare(`INSERT INTO receipts (
+             receipt_key, source_session_key, source_session_id, thread_id, expires_at, record_json
+           ) VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT(receipt_key) DO UPDATE SET
+             source_session_key = excluded.source_session_key,
+             source_session_id = excluded.source_session_id,
+             thread_id = excluded.thread_id,
+             expires_at = excluded.expires_at,
+             record_json = excluded.record_json`)
+            .run(receipt.receiptKey, receipt.sessionKey, receipt.sessionId, receipt.threadId, receipt.expiresAt, JSON.stringify(receipt));
+    }));
+}
+function findReceipt(database, identity, now) {
+    return runStateOperation("read a delivery receipt", () => {
+        database.prepare("DELETE FROM receipts WHERE expires_at <= ?").run(now);
+        const row = database
+            .prepare(`SELECT record_json FROM receipts
+         WHERE source_session_key = ? AND source_session_id = ? AND thread_id = ?
+           AND expires_at > ?
+         ORDER BY expires_at DESC LIMIT 1`)
+            .get(identity.sourceSessionKey, identity.sourceSessionId, identity.threadId, now);
+        return row ? parseReceipt(row.record_json) : undefined;
+    });
+}
+function findHandoffByRoute(database, routeKey) {
+    return runStateOperation("read a handoff", () => readHandoffByRoute(database, routeKey));
+}
+function insertHandoff(database, record) {
+    return runStateOperation("store a handoff", () => inTransaction(database, () => {
+        const existing = readHandoffByRoute(database, record.routeKey);
+        if (existing)
+            return { inserted: false, record: existing };
+        assertCapacity(database, "handoffs");
+        database
+            .prepare(`INSERT INTO handoffs (
+             route_key, target_session_key, handoff_id, state, attempt_count, last_attempted_at,
+             record_json
+           ) VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(record.routeKey, record.targetSessionKey, record.handoffId, record.state, record.attemptCount, record.lastAttemptedAt ?? null, JSON.stringify(record));
+        return { inserted: true, record };
+    }));
+}
+function readHandoffByRoute(database, routeKey) {
+    const row = database
+        .prepare("SELECT record_json FROM handoffs WHERE route_key = ?")
+        .get(routeKey);
+    return row ? parseHandoff(row.record_json) : undefined;
+}
+function claimHandoff(database, identity, now) {
+    return runStateOperation("claim a handoff", () => inTransaction(database, () => {
+        const row = findClaimRow(database, identity);
+        if (!row)
+            return { status: "none" };
+        const record = parseHandoff(row.record_json);
+        assertClaimIdentity(record, identity);
+        if (record.state === "claimed") {
+            return { status: sameClaimant(record, identity) ? "claimed" : "alreadyClaimed", record };
+        }
+        const claimed = {
+            ...record,
+            state: "claimed",
+            claimedAt: now,
+            claimedBy: {
+                sessionId: identity.sessionId,
+                ...(identity.runId !== undefined ? { runId: identity.runId } : {}),
+            },
+        };
+        const result = database
+            .prepare(`UPDATE handoffs SET state = 'claimed', record_json = ?
+           WHERE route_key = ? AND state = 'pending'`)
+            .run(JSON.stringify(claimed), record.routeKey);
+        if (result.changes === 1)
+            return { status: "claimed", record: claimed };
+        const current = readHandoffByRoute(database, record.routeKey);
+        if (!current)
+            return { status: "none" };
+        return {
+            status: sameClaimant(current, identity) ? "claimed" : "alreadyClaimed",
+            record: current,
+        };
+    }));
+}
+function sameClaimant(record, identity) {
+    if (!record.claimedBy)
+        return false;
+    if (identity.runId !== undefined)
+        return record.claimedBy.runId === identity.runId;
+    return record.claimedBy.runId === undefined && record.claimedBy.sessionId === identity.sessionId;
+}
+function findClaimRow(database, identity) {
+    if (identity.handoffId !== undefined) {
+        return database
+            .prepare("SELECT record_json FROM handoffs WHERE handoff_id = ?")
+            .get(identity.handoffId);
+    }
+    return database
+        .prepare("SELECT record_json FROM handoffs WHERE target_session_key = ?")
+        .get(identity.targetSessionKey);
+}
+function assertClaimIdentity(record, identity) {
+    if (record.targetSessionKey !== identity.targetSessionKey ||
+        record.agentId !== identity.agentId ||
+        record.accountId !== identity.accountId ||
+        (identity.handoffId !== undefined && record.handoffId !== identity.handoffId)) {
+        throw new HandoffError("invalidTarget", "This session cannot claim the requested handoff.");
+    }
+}
+function recordAttempt(database, routeKey, startedAt) {
+    return runStateOperation("record a handoff attempt", () => inTransaction(database, () => {
+        const current = readHandoffByRoute(database, routeKey);
+        if (current?.state !== "pending")
+            return current;
+        const updated = {
+            ...current,
+            attemptCount: current.attemptCount + 1,
+            lastAttemptedAt: startedAt,
+        };
+        database
+            .prepare(`UPDATE handoffs SET attempt_count = ?, last_attempted_at = ?, record_json = ?
+           WHERE route_key = ? AND state = 'pending'`)
+            .run(updated.attemptCount, startedAt, JSON.stringify(updated), routeKey);
+        return updated;
+    }));
+}
+function recordAttemptEnd(database, routeKey, endedAt) {
+    return runStateOperation("record a handoff attempt end", () => inTransaction(database, () => {
+        const current = readHandoffByRoute(database, routeKey);
+        if (current?.state !== "pending")
+            return current;
+        const updated = { ...current, lastAttemptedAt: endedAt };
+        database
+            .prepare(`UPDATE handoffs SET last_attempted_at = ?, record_json = ?
+           WHERE route_key = ? AND state = 'pending'`)
+            .run(endedAt, JSON.stringify(updated), routeKey);
+        return updated;
+    }));
+}
+function listPending(database, query) {
+    return runStateOperation("list pending handoffs", () => {
+        const rows = database
+            .prepare(`SELECT record_json FROM handoffs
+         WHERE state = 'pending' AND attempt_count < ?
+           AND (last_attempted_at IS NULL OR last_attempted_at <= ?)
+         ORDER BY COALESCE(last_attempted_at, 0), rowid`)
+            .all(query.maxAttempts, query.now - query.spacingMs);
+        return rows.map((row) => parseHandoff(row.record_json));
+    });
+}
+function listReceipts(database, now) {
+    return runStateOperation("list receipts", () => {
+        database.prepare("DELETE FROM receipts WHERE expires_at <= ?").run(now);
+        const rows = database
+            .prepare("SELECT record_json FROM receipts WHERE expires_at > ? ORDER BY rowid")
+            .all(now);
+        return rows.map((row) => parseReceipt(row.record_json));
+    });
+}
+function listHandoffs(database) {
+    return runStateOperation("list handoffs", () => {
+        const rows = database
+            .prepare("SELECT record_json FROM handoffs ORDER BY rowid")
+            .all();
+        return rows.map((row) => parseHandoff(row.record_json));
+    });
+}
+function retireHandoff(database, handoffId, options) {
+    return runStateOperation("retire a handoff", () => inTransaction(database, () => {
+        const row = database
+            .prepare("SELECT record_json FROM handoffs WHERE handoff_id = ?")
+            .get(handoffId);
+        if (!row)
+            return false;
+        const record = parseHandoff(row.record_json);
+        if (record.state === "pending" && !options.force) {
+            throw new HandoffError("conflictingHandoff", "This handoff is pending; pass --force to retire it anyway.");
+        }
+        const result = database.prepare("DELETE FROM handoffs WHERE handoff_id = ?").run(handoffId);
+        return result.changes === 1;
+    }));
+}
+function assertCapacity(database, table) {
+    const row = database.prepare(`SELECT COUNT(*) AS count FROM ${table}`).get();
+    if (row.count < STORE_CAPACITY)
+        return;
+    const error = new Error(`${table} capacity ${STORE_CAPACITY} reached.`);
+    Object.assign(error, { code: "STORE_LIMIT_EXCEEDED" });
+    throw error;
+}
+function inTransaction(database, operation) {
+    database.exec("BEGIN IMMEDIATE;");
+    try {
+        const result = operation();
+        database.exec("COMMIT;");
+        return result;
+    }
+    catch (error) {
+        try {
+            database.exec("ROLLBACK;");
+        }
+        catch {
+            // Preserve the operation failure.
+        }
+        throw error;
+    }
+}
+function runStateOperation(description, operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        if (error instanceof HandoffError)
+            throw error;
+        throw persistentStateError(`Could not ${description}: ${errorMessage(error)}`, error);
+    }
+}
+function persistentStateError(message, cause) {
+    return new HandoffError("unavailablePersistentState", message, cause);
+}
+function parseReceipt(json) {
+    const value = parseRecord(json, "delivery receipt");
+    if (value.schemaVersion !== 1 ||
+        typeof value.receiptKey !== "string" ||
+        typeof value.sessionKey !== "string" ||
+        typeof value.sessionId !== "string" ||
+        typeof value.threadId !== "string" ||
+        typeof value.starterText !== "string" ||
+        typeof value.expiresAt !== "number") {
+        throw new Error("Invalid delivery receipt record.");
+    }
+    return value;
+}
+function parseHandoff(json) {
+    const value = parseRecord(json, "handoff");
+    if (value.schemaVersion !== 2 ||
+        typeof value.routeKey !== "string" ||
+        typeof value.handoffId !== "string" ||
+        typeof value.targetSessionKey !== "string" ||
+        typeof value.agentId !== "string" ||
+        typeof value.sessionKey !== "string" ||
+        typeof value.threadId !== "string" ||
+        typeof value.starterText !== "string" ||
+        typeof value.attemptCount !== "number" ||
+        (value.state !== "pending" && value.state !== "claimed")) {
+        throw new Error("Invalid handoff record.");
+    }
+    return value;
+}
+function parseRecord(json, label) {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error(`Corrupt ${label} JSON.`, { cause: error });
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Invalid ${label} record.`);
+    }
+    return value;
+}

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

@@ -0,0 +1,29 @@
+import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk/plugin-entry";
+import { Type } from "typebox";
+import type { ReceiptCoordinator } from "./receipts.js";
+import type { RunIdCache } from "./run-ids.js";
+import type { HandoffService } from "./service.js";
+import type { HandoffStore } from "./state.js";
+import type { PluginConfiguration, ToolSuccess } from "./types.js";
+export interface ThreadHandoffToolParams {
+    context: OpenClawPluginToolContext;
+    configuration: PluginConfiguration;
+    receipts: ReceiptCoordinator;
+    runIds: RunIdCache;
+    getStore: () => HandoffStore;
+    service: HandoffService;
+    now?: () => number;
+}
+export declare function createThreadHandoffTool(params: ThreadHandoffToolParams): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TUnion<[Type.TObject<{
+        action: Type.TLiteral<"start">;
+        threadId: Type.TString;
+    }>, Type.TObject<{
+        action: Type.TLiteral<"claim">;
+        handoffId: Type.TOptional<Type.TString>;
+    }>]>;
+    execute(_toolCallId: string, input: unknown): Promise<import("openclaw/plugin-sdk/tool-results").AgentToolResult<ToolSuccess>>;
+};

package/dist/thread-handoff/tool.js

@@ -0,0 +1,168 @@
+import { randomUUID } from "node:crypto";
+import { jsonResult } from "openclaw/plugin-sdk/tool-results";
+import { Type } from "typebox";
+import { HandoffError } from "./errors.js";
+import { assertSupportedSource, createHandoffRecord, evidenceMatches, readSourceContext, resolveHandoffRoute, } from "./routing.js";
+import { nonempty } from "./values.js";
+const threadHandoffParameters = Type.Union([
+    Type.Object({
+        action: Type.Literal("start"),
+        threadId: Type.String({ minLength: 1 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        action: Type.Literal("claim"),
+        handoffId: Type.Optional(Type.String()),
+    }, { additionalProperties: false }),
+]);
+export function createThreadHandoffTool(params) {
+    params.receipts.captureContext(params.context);
+    return {
+        name: "thread_handoff",
+        label: "Thread handoff",
+        description: "Start a confirmed native thread session or claim its durable handoff before task work.",
+        parameters: threadHandoffParameters,
+        async execute(_toolCallId, input) {
+            try {
+                const result = await executeAction(params, parseInput(input));
+                return jsonResult(result);
+            }
+            catch (error) {
+                throw presentError(error);
+            }
+        },
+    };
+}
+async function executeAction(params, input) {
+    const source = readSourceContext(params.context, params.configuration);
+    if (!source) {
+        throw new HandoffError("unsupportedContext", "Trusted channel session context is unavailable.");
+    }
+    if (input.action === "claim")
+        return claimHandoff(params, source, input.handoffId);
+    return startHandoff(params, source, input.threadId);
+}
+function claimHandoff(params, source, handoffId) {
+    const runId = params.runIds.read(source.sessionKey, source.sessionId);
+    const result = params.getStore().claimHandoff({
+        targetSessionKey: source.sessionKey,
+        agentId: source.agentId,
+        sessionId: source.sessionId,
+        ...(runId !== undefined ? { runId } : {}),
+        ...(source.accountId ? { accountId: source.accountId } : {}),
+        ...(handoffId ? { handoffId } : {}),
+    }, (params.now ?? Date.now)());
+    if (handoffId && result.status === "none") {
+        throw new HandoffError("invalidTarget", "The requested handoff does not exist.");
+    }
+    return {
+        status: result.status,
+        ...(result.status === "alreadyClaimed" && result.record?.claimedAt !== undefined
+            ? { claimedAt: result.record.claimedAt }
+            : {}),
+    };
+}
+async function startHandoff(params, source, threadId) {
+    const surface = assertSupportedSource(source, params.configuration);
+    const route = resolveHandoffRoute(source, threadId, surface);
+    return params.service.runForTarget(route.targetSessionKey, async () => {
+        const store = params.getStore();
+        const existing = store.findHandoffByRoute(route.routeKey);
+        if (existing) {
+            if (!sourceMatchesExisting(existing, source, threadId))
+                throw conflictingHandoff();
+            return resumeExisting(params.service, existing);
+        }
+        const receipt = await params.receipts.waitForReceipt({
+            sourceSessionKey: source.sessionKey,
+            sourceSessionId: source.sessionId,
+            threadId,
+        });
+        if (!receipt) {
+            throw new HandoffError("unverifiedThreadDelivery", "No confirmed starter delivery exists for this thread in the current session.");
+        }
+        const record = createHandoffRecord({
+            receipt,
+            route,
+            handoffId: randomUUID(),
+            createdAt: (params.now ?? Date.now)(),
+        });
+        const inserted = store.insertHandoff(record);
+        if (!inserted.inserted) {
+            if (!evidenceMatches(inserted.record, receipt))
+                throw conflictingHandoff();
+            return resumeExisting(params.service, inserted.record);
+        }
+        await params.service.startTurn(record);
+        return { status: "queued", handoffId: record.handoffId, sessionKey: record.targetSessionKey };
+    });
+}
+function sourceMatchesExisting(record, source, threadId) {
+    return (record.sessionKey === source.sessionKey &&
+        record.sessionId === source.sessionId &&
+        record.agentId === source.agentId &&
+        record.channelId === source.channelId &&
+        record.accountId === source.accountId &&
+        record.parentConversationId === source.parentConversationId &&
+        record.threadId === threadId);
+}
+function conflictingHandoff() {
+    return new HandoffError("conflictingHandoff", "This target already belongs to different delivery evidence.");
+}
+/** A record whose first attempt never started gets its seed now; otherwise nothing to redo. */
+async function resumeExisting(service, record) {
+    if (record.state === "pending" && record.attemptCount === 0)
+        await service.startTurn(record);
+    return {
+        status: "alreadyStarted",
+        handoffId: record.handoffId,
+        sessionKey: record.targetSessionKey,
+    };
+}
+function parseInput(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return invalidInput();
+    const record = value;
+    const keys = Object.keys(record);
+    if (record.action === "start") {
+        if (keys.some((key) => key !== "action" && key !== "threadId"))
+            return invalidInput();
+        return { action: "start", threadId: requiredString(record.threadId) };
+    }
+    if (record.action === "claim") {
+        if (keys.some((key) => key !== "action" && key !== "handoffId"))
+            return invalidInput();
+        const handoffId = blankAsAbsent(record.handoffId);
+        return { action: "claim", ...(handoffId ? { handoffId } : {}) };
+    }
+    return invalidInput();
+}
+// A human turn without a seed sometimes sends `handoffId: ""` rather than omitting the field.
+function blankAsAbsent(value) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string")
+        return invalidInput();
+    return nonempty(value);
+}
+function requiredString(value) {
+    const normalized = optionalString(value);
+    if (!normalized)
+        return invalidInput();
+    return normalized;
+}
+function optionalString(value) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string" || value.trim().length === 0)
+        return invalidInput();
+    return value.trim();
+}
+function invalidInput() {
+    throw new HandoffError("invalidTarget", "Invalid thread_handoff input.");
+}
+function presentError(error) {
+    if (!(error instanceof HandoffError))
+        return error instanceof Error ? error : new Error(String(error));
+    const cause = error.causeCode ? ` (${error.causeCode})` : "";
+    return new Error(`${error.code}${cause}: ${error.message}`, { cause: error });
+}

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

@@ -0,0 +1,69 @@
+export interface DeliveryRoute {
+    channel: string;
+    to: string;
+    accountId?: string;
+    threadId?: string;
+}
+export interface TurnRequest {
+    sessionKey: string;
+    agentId: string;
+    channelId: string;
+    surface: "slack" | "discord";
+    route: DeliveryRoute;
+    parentConversationId: string;
+    message: string;
+    messageId: string;
+}
+export interface SourceContext {
+    agentId: string;
+    sessionKey: string;
+    sessionId: string;
+    channelId: string;
+    accountId?: string;
+    parentConversationId: string;
+    deliveryContext?: DeliveryRoute;
+}
+export interface DeliveryReceipt extends SourceContext {
+    schemaVersion: 1;
+    receiptKey: string;
+    threadId: string;
+    starterMessageId?: string;
+    starterText: string;
+    toolCallId?: string;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface HandoffRecord extends SourceContext {
+    schemaVersion: 2;
+    routeKey: string;
+    handoffId: string;
+    targetSessionKey: string;
+    threadId: string;
+    starterMessageId?: string;
+    starterText: string;
+    deliveryContext: DeliveryRoute;
+    createdAt: number;
+    attemptCount: number;
+    lastAttemptedAt?: number;
+    state: "pending" | "claimed";
+    claimedAt?: number;
+    claimedBy?: {
+        sessionId: string;
+        runId?: string;
+    };
+}
+export interface ReceiptIdentity {
+    sourceSessionKey: string;
+    sourceSessionId: string;
+    threadId: string;
+}
+export interface PluginConfiguration {
+    channelSurfaces: Record<string, "slack" | "discord">;
+}
+export interface ToolSuccess {
+    status: "queued" | "alreadyStarted" | "claimed" | "alreadyClaimed" | "none";
+    handoffId?: string;
+    sessionKey?: string;
+    claimedAt?: number;
+}
+export type HandoffErrorCode = "unsupportedContext" | "unverifiedThreadDelivery" | "conflictingHandoff" | "invalidTarget" | "unavailablePersistentState";

package/dist/thread-handoff/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+export declare function nonempty(value: unknown): string | undefined;
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function errorMessage(error: unknown): string;

package/dist/thread-handoff/values.js

@@ -0,0 +1,14 @@
+export function nonempty(value) {
+    if (typeof value !== "string")
+        return;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/openclaw.plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "alignfirst-service",
+  "name": "AlignFirst Service",
+  "description": "OpenClaw capabilities for the AlignFirst Dev Kit.",
+  "activation": { "onStartup": true },
+  "contracts": { "tools": ["thread_handoff"] },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "channelSurfaces": {
+        "type": "object",
+        "additionalProperties": { "enum": ["slack", "discord"] },
+        "default": { "slack": "slack", "discord": "discord" }
+      }
+    }
+  }
+}