@velanir/openclaw-pending-context 0.4.0

package/README.md

@@ -0,0 +1,54 @@
+# @velanir/openclaw-pending-context
+
+`@velanir/openclaw-pending-context` makes an interactive scheduling reply safe
+to interpret without treating an old transcript mirror as workflow state.
+
+## Canonical 0.4.0 behavior
+
+1. It reads pending state only from the responsibility runner and injects it
+   only when the exact agent, channel, session/conversation, account, and
+   authenticated user match. Strict user and session scope both default on.
+2. It registers `responsibility_pending` first, then
+   `responsibility_select_option`, `responsibility_reject`,
+   `responsibility_change`, and `responsibility_status`. A model never passes a
+   `userMessageId`; a host-observed inbound message is bound internally through
+   the manifest-declared trusted tool policy.
+3. It quiets only a fresh inbound run that has matching pending context. With
+   `suppressNonFinalReplies=true` (the default), tool/progress reply payloads
+   for that run are cancelled. Ordinary chat and stale/unscoped sessions are
+   not put into global final-only mode.
+4. The first admitted action ends the run's tool budget. Later tool calls are
+   blocked. The final reply and the persisted assistant message are rewritten
+   from the authoritative runner receipt; a model claim that a meeting was
+   scheduled without an action is replaced with a truthful failure.
+5. A scheduling-success final requires a non-dry-run `select_option` receipt
+   with an Outlook event id, Zoom join URL, and counterpart-reply receipt.
+   Partial results, errors, and dry runs never become success claims.
+
+The package deliberately chose the stronger Riley/Mae common behavior as the
+source of truth. It does not copy live compiled bytes or make ordinary Teams
+chat quiet merely because a responsibility happens to have pending work.
+
+## Rollout and rollback
+
+`dryRun` defaults to `true`. Set it to `false` only for a reviewed canary.
+That alone still cannot execute an effect: the source must declare an explicit
+`actionCommand`; there is no default effect argv. Roll back immediately by
+setting `dryRun` to `true`, or set `suppressNonFinalReplies` to `false` for
+diagnosis while preserving the receipt/final guard.
+
+The plugin requires an OpenClaw runtime compatible with `2026.7.1-beta.5` or
+newer and declares its trusted policy in `openclaw.plugin.json`. Platform
+rendering/install work owns canary selection and the exact reviewed action
+bridge; this package does not deploy itself or modify runner business logic.
+
+## Develop
+
+```bash
+pnpm --filter=@velanir/openclaw-pending-context test
+pnpm --filter=@velanir/openclaw-pending-context check-types
+pnpm --filter=@velanir/openclaw-pending-context build
+```
+
+`DESIGN.md` documents the original phase-one pending-state contract. This README
+and the source/tests are the canonical 0.4.0 finalization contract.

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+type PluginLogger = {
+    debug?: (message: string) => void;
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+    error?: (message: string) => void;
+};
+type AgentToolLike = {
+    name: string;
+    label: string;
+    description: string;
+    parameters: unknown;
+    execute: (toolCallId: string, params: unknown, signal?: unknown, onUpdate?: unknown) => Promise<AgentToolResultLike>;
+};
+type AgentToolResultLike = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: unknown;
+};
+type ToolFactoryContext = {
+    agentId?: string;
+    sessionKey?: string;
+    messageChannel?: string;
+    agentAccountId?: string;
+    requesterSenderId?: string;
+    requesterMessageId?: string;
+    deliveryContext?: {
+        channel?: string;
+        accountId?: string;
+        to?: string;
+        threadId?: string | number;
+    };
+};
+type AgentToolFactory = (ctx: ToolFactoryContext) => AgentToolLike | AgentToolLike[] | null | undefined;
+type AgentTurnPrepareContext = {
+    runId?: string;
+    agentId?: string;
+    sessionKey?: string;
+    channel?: string;
+    channelId?: string;
+    chatId?: string;
+    senderId?: string;
+    messageProvider?: string;
+    workspaceDir?: string;
+};
+type PluginJsonValue = null | boolean | number | string | PluginJsonValue[] | {
+    [key: string]: PluginJsonValue;
+};
+type SessionExtensionRegistration = {
+    namespace: string;
+    description: string;
+    project?: (ctx: {
+        sessionKey: string;
+        sessionId?: string;
+        state: PluginJsonValue | undefined;
+    }) => PluginJsonValue | undefined;
+};
+type TrustedToolPolicyEvent = {
+    toolName: string;
+    params: Record<string, unknown>;
+    runId?: string;
+    toolCallId?: string;
+};
+type TrustedToolPolicyContext = {
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    runId?: string;
+    toolName: string;
+    toolCallId?: string;
+    channelId?: string;
+    getSessionExtension?: (namespace: string) => PluginJsonValue | undefined;
+};
+type TrustedToolPolicyDecision = {
+    params?: Record<string, unknown>;
+    block?: boolean;
+    blockReason?: string;
+};
+type TrustedToolPolicyRegistration = {
+    id: string;
+    description: string;
+    evaluate: (event: TrustedToolPolicyEvent, ctx: TrustedToolPolicyContext) => TrustedToolPolicyDecision | void | Promise<TrustedToolPolicyDecision | void>;
+};
+type RunContextPatch = {
+    runId: string;
+    namespace: string;
+    value?: PluginJsonValue;
+    unset?: boolean;
+};
+type RunContextQuery = {
+    runId: string;
+    namespace: string;
+};
+type OpenClawPluginApi = {
+    pluginConfig?: Record<string, unknown>;
+    logger?: PluginLogger;
+    setRunContext?: (patch: RunContextPatch) => boolean;
+    getRunContext?: (params: RunContextQuery) => PluginJsonValue | undefined;
+    runContext?: {
+        setRunContext: (patch: RunContextPatch) => boolean;
+        getRunContext: (params: RunContextQuery) => PluginJsonValue | undefined;
+    };
+    registerTool: (tool: AgentToolLike | AgentToolFactory, opts?: {
+        name?: string;
+        names?: string[];
+        optional?: boolean;
+    }) => void;
+    registerSessionExtension: (extension: SessionExtensionRegistration) => void;
+    registerTrustedToolPolicy: (policy: TrustedToolPolicyRegistration) => void;
+    on: (hookName: string, handler: (event: unknown, ctx: unknown) => unknown | Promise<unknown>, opts?: {
+        priority?: number;
+        timeoutMs?: number;
+    }) => void;
+};
+
+type TurnScope = {
+    agentId?: string;
+    channel?: string;
+    userId?: string;
+    sessionKey?: string;
+    accountId?: string;
+    conversationId?: string;
+};
+
+type TrustedInboundAuthorization = {
+    messageId: string;
+    senderId: string;
+    sessionKey: string;
+    runId?: string;
+    channel?: string;
+    accountId?: string;
+    conversationId?: string;
+    receivedAt: number;
+};
+type InboundHookEvent = {
+    messageId?: string;
+    senderId?: string;
+    from?: string;
+    sessionKey?: string;
+    runId?: string;
+    channel?: string;
+};
+type InboundHookContext = {
+    messageId?: string;
+    senderId?: string;
+    sessionKey?: string;
+    runId?: string;
+    channelId?: string;
+    accountId?: string;
+    conversationId?: string;
+};
+type ToolBindEvent = {
+    toolName?: string;
+    toolCallId?: string;
+    runId?: string;
+};
+type ToolBindContext = {
+    toolName?: string;
+    toolCallId?: string;
+    runId?: string;
+    sessionKey?: string;
+};
+type AuthorizationConsumeError = "missing_binding" | "message_replayed" | "session_mismatch" | "user_mismatch";
+type AuthorizationConsumeResult = {
+    authorization: TrustedInboundAuthorization | null;
+    error?: AuthorizationConsumeError;
+};
+type InboundAuthorizationStore = {
+    recordTrusted(record: TrustedInboundAuthorization): boolean;
+    recordInbound(event: InboundHookEvent, ctx: InboundHookContext): boolean;
+    bindTool(event: ToolBindEvent, ctx: ToolBindContext): boolean;
+    hasFreshBinding(scope: TurnScope, runId?: string): boolean;
+    consumeDetailed(toolCallId: string, scope: TurnScope): AuthorizationConsumeResult;
+    consume(toolCallId: string, scope: TurnScope): TrustedInboundAuthorization | null;
+};
+
+type DeliveryHookEvent = {
+    runId?: string;
+    toolName?: string;
+    toolCallId?: string;
+    result?: unknown;
+    error?: unknown;
+    kind?: string;
+};
+type DeliveryHookContext = {
+    runId?: string;
+    toolName?: string;
+    toolCallId?: string;
+    sessionKey?: string;
+};
+type TransactionDeliveryStore = {
+    markPendingTurn(runIdValue: unknown, sessionKeyValue: unknown): boolean;
+    beginAction(event: DeliveryHookEvent, ctx: DeliveryHookContext): {
+        tracked: boolean;
+        duplicate: boolean;
+    };
+    failAction(event: DeliveryHookEvent, ctx: DeliveryHookContext, errorCode: string | undefined): boolean;
+    finishAction(event: DeliveryHookEvent, ctx: DeliveryHookContext): boolean;
+    blockFurtherTool(event: DeliveryHookEvent, ctx: DeliveryHookContext): boolean;
+    suppressNonFinal(event: DeliveryHookEvent): boolean;
+    expectedFinalText(runIdValue: unknown): string | undefined;
+    expectedFinalTextForToolCall(toolCallIdValue: unknown): string | undefined;
+    pendingWithoutAction(runIdValue: unknown): boolean;
+    claimNoActionFailureForSession(sessionKeyValue: unknown): string | undefined;
+    authoritativeFinalForSession(sessionKeyValue: unknown, modelClaimsSuccess: boolean): string | undefined;
+    markFinalDelivered(sessionKeyValue: unknown): boolean;
+    finalAlreadyDelivered(sessionKeyValue: unknown): boolean;
+    claimFinalTextForSession(sessionKeyValue: unknown): string | undefined;
+    finalizeReply(event: DeliveryHookEvent): {
+        text?: string;
+    } | undefined;
+};
+
+type RunnerExecInput = {
+    command: string[];
+    cwd: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    stdin?: string;
+};
+type RunnerExecResult = {
+    ok: boolean;
+    stdout?: string;
+    error?: string;
+    truncated?: boolean;
+};
+type RunnerExec = (input: RunnerExecInput) => RunnerExecResult;
+
+declare const PLUGIN_ID = "velanir-pending-context";
+declare const TRUSTED_ACTION_POLICY_ID = "authoritative-pending-action";
+type PendingContextRuntime = {
+    authorization?: InboundAuthorizationStore;
+    delivery?: TransactionDeliveryStore;
+};
+declare function turnScopeFromContext(ctx: AgentTurnPrepareContext): TurnScope;
+declare function toolScopeFromContext(ctx: ToolFactoryContext): TurnScope;
+declare function registerPendingContextPlugin(api: OpenClawPluginApi, exec: RunnerExec, runtime?: PendingContextRuntime): void;
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: OpenClawPluginApi): void;
+};
+
+export { PLUGIN_ID, type PendingContextRuntime, TRUSTED_ACTION_POLICY_ID, _default as default, registerPendingContextPlugin, toolScopeFromContext, turnScopeFromContext };