@pushary/openclaw 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pushary
+
+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

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# @pushary/openclaw
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Phone approvals for [OpenClaw](https://openclaw.ai). Before your OpenClaw agent runs a gated tool call, Pushary asks you on your phone. The call runs only after you tap Approve. Anything else blocks it.
+
+It is built for an OpenClaw that runs for you alone, often always on, on a small VPS. It works on the Agent and Agent Pro plans, with push approvals on your phone. Phone calls are not available for OpenClaw yet.
+
+## Install
+
+Run the Pushary CLI on the machine that runs OpenClaw, as the user the gateway runs as:
+
+```bash
+npx pushary@latest setup --agents openclaw
+```
+
+Setup signs you in, saves your key in `~/.pushary/config.json`, writes this plugin to `~/.pushary/openclaw-plugin`, and runs:
+
+```bash
+openclaw plugins install ~/.pushary/openclaw-plugin --force --accept-capabilities
+openclaw plugins enable pushary --accept-capabilities
+```
+
+The CLI carries the plugin itself, so `npx pushary@latest upgrade`, or running setup again, installs the newer copy. A running gateway picks up the plugin when the install finishes; a stopped one loads it at its next start. Check it with:
+
+```bash
+openclaw plugins inspect pushary --runtime --json
+```
+
+`typedHooks` should list `before_tool_call`. Requires OpenClaw 2026.11.3 or later and Node 24.16 or later.
+
+If the gateway runs as another user, or as a service without that home folder, put the key in that user's `~/.openclaw/.env` and restart the gateway:
+
+```bash
+PUSHARY_API_KEY=pk_your_key
+```
+
+## What it gates
+
+- Every `exec` call.
+- The `process` actions that send input to a running session: `write`, `send-keys`, `submit` and `paste`. `process send-keys` can type a command into a session that `exec` started in the background, so it asks like `exec` does. `list`, `poll`, `log`, `kill`, `clear` and `remove` do not ask.
+- The actions that could switch the gate off or change OpenClaw itself: `plugins` `install`, `enable`, `disable`, `uninstall`, `reload` and `reloadAndResume`; `gateway` `update.run`; and every `openclaw` action that changes config, plugins, agents, channels or the gateway. Their read actions (`plugins` `list`, `inspect` and `search`; `gateway` `config.get` and `config.schema.lookup`; `openclaw` `status`, `config_get`, `plugin_list` and the other reads) do not ask. An action the plugin does not know asks.
+
+- Every `automations` (also called `cron`) action except `status`, `list`, `get`, `runs` and `next_check`. A scheduled job can run a command outside `before_tool_call`, so adding, changing, running or waking one asks.
+- Every `terminal` action except `read` and `list`. `terminal input` types into a shared operator terminal.
+- A `sessions_spawn` with a `cwd` outside the agent's workspace or in its `hooks` folder, or with a `projectId`, `projectGitUrl` or `worktree`. The question names the folder.
+- Every `write`, `edit` or `apply_patch` into OpenClaw's own files: anything inside an OpenClaw state directory, `~/.config/openclaw` (where Linux keeps `gateway.env`), `~/.pushary`, the `.env` in the gateway's working folder, the config file set by `OPENCLAW_CONFIG_PATH`, and the launchd and systemd files OpenClaw installs for its gateway. The one exception is the agent's own workspace when it lives inside the state directory, which is OpenClaw's default (`~/.openclaw/workspace`). The workspace `hooks` folder always asks, wherever the workspace is, because OpenClaw can load hooks from it as code. The plugin resolves `~`, `@` references, `file://` paths, relative paths against the agent's workspace, and symlinks before it decides, and a path it cannot resolve asks. Writes anywhere else run without asking.
+
+To gate more tools, list their OpenClaw tool ids. The list adds to the defaults above; it never replaces them:
+
+```json5
+{
+  plugins: {
+    entries: {
+      pushary: {
+        enabled: true,
+        config: { gatedTools: ["message", "browser"] },
+      },
+    },
+  },
+}
+```
+
+Ids are read the way OpenClaw names its tools: `bash` means `exec`, `cron` means `automations` and `tool_call` means `dispatch_action`. An entry that is not a tool id gates nothing, and the plugin logs it as an error when it starts. OpenClaw does not mark a tool call as a message send, a payment or a public post, so gate those by naming the tool that does it, such as `message`.
+
+## What happens to a gated call
+
+| Pushary says | The call |
+| --- | --- |
+| You answer yes | Runs |
+| You answer anything else | Blocked, and the agent is told not to retry |
+| No answer before the wait ends | Blocked, and the question is withdrawn |
+| OpenClaw cancels the run | Blocked, and the question is withdrawn |
+| The agent was stopped from Pushary | Blocked |
+| No phone, browser or Slack is connected | Blocked, with a link to connect one |
+| Pushary cannot be reached, rejects the key or sends a reply the plugin cannot read | Blocked |
+| Your delivery mode keeps approvals off the phone, or a When away push window passes with no answer | Withdrawn in Pushary and handed to OpenClaw's own approval prompt, which blocks the call when nobody can answer there. On an OpenClaw older than 2026.11.3 the call is blocked instead |
+
+A missing answer never becomes an approval. A plugin error or timeout blocks the call: OpenClaw fails closed when a `before_tool_call` hook throws or runs out of time, and the plugin turns its own errors into a block rather than relying on that.
+
+## How long it waits
+
+The plugin asks OpenClaw for a five minute `before_tool_call` budget and stops waiting ten seconds before it, so it has time to withdraw the question. If you set `plugins.entries.pushary.hooks.timeouts.before_tool_call` or `hooks.timeoutMs`, the plugin reads that value and ends its wait before it instead.
+
+## Where the key comes from
+
+1. `PUSHARY_API_KEY` in the gateway's environment, which OpenClaw also loads from `~/.openclaw/.env`.
+2. `apiKey` in `~/.pushary/config.json`, or the file named by `PUSHARY_CONFIG_FILE`.
+
+With no key, every gated call is blocked and the reason says how to fix it.
+
+## Removing it
+
+```bash
+npx pushary@latest clean
+```
+
+Clean uninstalls the plugin and puts back the `plugins.entries.pushary` settings you had before setup. Without the plugin, OpenClaw's own exec approvals still apply, and nothing reaches your phone.
+
+## Limits
+
+- The gate covers the tools listed above and any you add. It does not see other tools: for example the file-transfer plugin's `file_write` is not gated unless you add it to `gatedTools`.
+- ACP sessions set to approve everything, and CLI backends, run tools inside the external harness. Those tool calls never reach `before_tool_call`, so the plugin cannot gate them.
+- This is an approval layer, not a sandbox. Pair it with OpenClaw's own sandboxing and `tools.fs.workspaceOnly`.
+- The plugin talks only to `https://pushary.com` and `https://www.pushary.com`, the hosts the CLI uses. Any other `PUSHARY_BASE_URL` blocks every gated call, so a changed setting cannot point it at a server that always says yes.
+- The plugin is not told which folder a tool runs in. It resolves a relative path against the agent's workspace, any folder inside it, and the gateway's working folder, and a spawned session in any other folder asks first. A run started some other way in a folder inside OpenClaw's state is not covered.
+- Config `$include` files outside the state directory, including roots named by `OPENCLAW_INCLUDE_ROOTS`, are not protected.
+- Windows has not been tested.
+- Pushary's tool rules from the dashboard are not evaluated on the machine. Every gated call asks.
+- Another plugin that rewrites tool parameters can change what runs, including a plugin that runs before this one: OpenClaw gives each plugin its own copy of the call and keeps the earlier plugin's rewrite. Pushary shows and approves the parameters it was given.
+- The wait is held inside one gateway process. If the gateway restarts during a wait, OpenClaw drops the call and the question stays in Pushary until it expires.
+
+## License
+
+MIT

package/dist/api-key-shape.d.ts

@@ -0,0 +1,3 @@
+export declare const API_KEY_PREFIX_PATTERN: RegExp;
+export declare const API_KEY_PATTERN: RegExp;
+export declare const isValidApiKey: (value: string) => boolean;

package/dist/api-key-shape.js

@@ -0,0 +1,5 @@
+// Generated by scripts/generate-editor-redaction.mjs.
+const API_KEY_PREFIX_SHAPE = 'pk_[a-f0-9]+';
+export const API_KEY_PREFIX_PATTERN = new RegExp(`^${API_KEY_PREFIX_SHAPE}$`);
+export const API_KEY_PATTERN = new RegExp(`^${API_KEY_PREFIX_SHAPE}\\.[a-f0-9]+$`);
+export const isValidApiKey = (value) => API_KEY_PATTERN.test(value);

package/dist/approval-hook.d.ts

@@ -0,0 +1,23 @@
+import type { ConnectionReading, PusharyConnection } from './connection.js';
+import { type GateClock } from './gate.js';
+import { type HandBackSurface } from './gate-result.js';
+import { type OpenClawBeforeToolCallHandler, type OpenClawPluginApi } from './host-api.js';
+import type { FileWriteCall } from './protected-writes.js';
+import type { PusharyQuestions } from './pushary-client.js';
+import { type GateSettings } from './settings.js';
+export declare const SESSION_ID_MAX = 128;
+export interface GateEnvironment {
+    readonly readConnection: () => ConnectionReading;
+    readonly questionsFor: (connection: PusharyConnection) => PusharyQuestions;
+    readonly clock: GateClock;
+    readonly newRequestId: () => string;
+}
+export interface GateHandlerOptions {
+    readonly settings: GateSettings;
+    readonly holdMs: number;
+    readonly withdrawReserveMs: number;
+    readonly handBackSurface: HandBackSurface;
+    readonly reachesOpenClawState: (call: FileWriteCall) => boolean;
+}
+export declare const createApprovalGateHandler: (options: GateHandlerOptions, environment: GateEnvironment) => OpenClawBeforeToolCallHandler;
+export declare const registerApprovalGate: (api: OpenClawPluginApi, environment: GateEnvironment) => void;

package/dist/approval-hook.js

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+import { approvalQuestionFor } from './approval-question.js';
+import { runApprovalGate } from './gate.js';
+import { notConnectedResultFor, openClawResultFor } from './gate-result.js';
+import { holdMsWithin, hookBudgetFrom, REQUESTED_HOOK_TIMEOUT_MS } from './hook-budget.js';
+import { BEFORE_TOOL_CALL_HOOK, } from './host-api.js';
+import { handsBackToTheHost, hostSupportFrom, MIN_HOST_VERSION } from './host-version.js';
+import { openClawWriteGuardFor } from './openclaw-write-guard.js';
+import { askingAgentName, hookMatcherFor, hostToolId, needsApproval, readGateSettings } from './settings.js';
+export const SESSION_ID_MAX = 128;
+const MILLISECONDS_PER_SECOND = 1_000;
+const UNEXPECTED_FAILURE_REASON = 'The Pushary approval gate failed unexpectedly, so this tool call was blocked. Nothing ran.';
+const boundedSessionId = (value) => value.length <= SESSION_ID_MAX ? value : createHash('sha256').update(value, 'utf8').digest('hex');
+const sessionIdOf = (context) => {
+    const session = (context.sessionId ?? context.sessionKey)?.trim();
+    return session ? boundedSessionId(session) : undefined;
+};
+export const createApprovalGateHandler = (options, environment) => async (event, context) => {
+    const reachesOpenClawState = options.reachesOpenClawState({ toolId: hostToolId(event.toolName), event, agentId: context.agentId });
+    if (!needsApproval(options.settings, event) && !reachesOpenClawState)
+        return undefined;
+    const agentName = askingAgentName(context.agentId);
+    const question = approvalQuestionFor(event, agentName);
+    const reading = environment.readConnection();
+    if (reading.kind !== 'ready')
+        return notConnectedResultFor(reading.kind, question.toolName);
+    const sessionId = sessionIdOf(context);
+    const outcome = await runApprovalGate({
+        question,
+        agentName,
+        requestId: environment.newRequestId(),
+        holdMs: options.holdMs,
+        withdrawReserveMs: options.withdrawReserveMs,
+        ...(sessionId === undefined ? {} : { sessionId }),
+        ...(reading.connection.machineId === null ? {} : { machineId: reading.connection.machineId }),
+        ...(context.abortSignal === undefined ? {} : { signal: context.abortSignal }),
+    }, { questions: environment.questionsFor(reading.connection), clock: environment.clock });
+    return openClawResultFor(outcome, question, options.handBackSurface);
+};
+const failingClosed = (handler, api) => async (event, context) => {
+    try {
+        return await handler(event, context);
+    }
+    catch (error) {
+        api.logger.error(`pushary: approval gate failed for ${event.toolName}: ${String(error)}`);
+        return { block: true, blockReason: UNEXPECTED_FAILURE_REASON };
+    }
+};
+const gatedToolsLine = (settings) => settings.gatedTools.join(', ');
+const reportSettings = (api, reading) => {
+    if (reading.kind === 'invalid') {
+        api.logger.error(`pushary: plugins.entries.pushary.config.gatedTools must be a list of OpenClaw tool ids; it was ignored, and only ${gatedToolsLine(reading.settings)} ask`);
+    }
+    if (reading.kind === 'configured' && reading.rejected.length > 0) {
+        api.logger.error(`pushary: these gatedTools entries are not OpenClaw tool ids and gate nothing: ${reading.rejected.join(', ')}`);
+    }
+};
+const reportHostSupport = (api, support) => {
+    if (support.kind === 'supported')
+        return;
+    const found = support.kind === 'too_old' ? `OpenClaw ${support.version}` : 'an OpenClaw that does not report its version';
+    api.logger.warn(`pushary: this plugin is built for OpenClaw ${MIN_HOST_VERSION} or later and found ${found}; approvals that would go to OpenClaw's own prompt are blocked instead`);
+};
+const handBackSurfaceFor = (support) => (handsBackToTheHost(support) ? 'openclaw_prompt' : 'none');
+export const registerApprovalGate = (api, environment) => {
+    const reading = readGateSettings(api.pluginConfig);
+    reportSettings(api, reading);
+    const support = hostSupportFrom(api.runtime);
+    reportHostSupport(api, support);
+    const hookTimeoutMs = hookBudgetFrom(api.config, api.id).timeoutMs;
+    const holdMs = holdMsWithin(hookTimeoutMs);
+    const handlerOptions = {
+        settings: reading.settings,
+        holdMs,
+        withdrawReserveMs: hookTimeoutMs - holdMs,
+        handBackSurface: handBackSurfaceFor(support),
+        reachesOpenClawState: openClawWriteGuardFor(api),
+    };
+    const handler = failingClosed(createApprovalGateHandler(handlerOptions, environment), api);
+    try {
+        api.on(BEFORE_TOOL_CALL_HOOK, handler, { matcher: hookMatcherFor(reading.settings), timeoutMs: REQUESTED_HOOK_TIMEOUT_MS });
+    }
+    catch (error) {
+        api.logger.error(`pushary: OpenClaw refused the tool list (${String(error)}), so every tool call is checked against it by name instead`);
+        api.on(BEFORE_TOOL_CALL_HOOK, handler, { timeoutMs: REQUESTED_HOOK_TIMEOUT_MS });
+    }
+    api.logger.info(`pushary: asking before ${gatedToolsLine(reading.settings)}, waiting up to ${Math.round(holdMs / MILLISECONDS_PER_SECOND)} s for an answer`);
+};

package/dist/approval-question.d.ts

@@ -0,0 +1,19 @@
+import type { OpenClawBeforeToolCallEvent } from './host-api.js';
+export declare const QUESTION_SUMMARY_MAX = 160;
+export declare const CONTEXT_MAX = 500;
+export declare const ACTION_MAX = 500;
+export declare const ACTION_BODY_MAX = 4000;
+export declare const TOOL_TARGET_MAX = 80;
+export declare const TOOL_NAME_MAX = 100;
+export declare const APPROVAL_TITLE_MAX = 80;
+export declare const APPROVAL_DESCRIPTION_MAX = 512;
+export interface ApprovalQuestion {
+    readonly question: string;
+    readonly context: string;
+    readonly toolName: string;
+    readonly toolTarget: string | undefined;
+    readonly action: string;
+    readonly actionBody: string;
+}
+export declare const truncated: (text: string, max: number) => string;
+export declare const approvalQuestionFor: (event: OpenClawBeforeToolCallEvent, agentName: string) => ApprovalQuestion;

package/dist/approval-question.js

@@ -0,0 +1,66 @@
+import { redactSecrets, redactSecretsDeep } from './redaction.js';
+import { SESSIONS_SPAWN_TOOL, SPAWN_FOLDER_PARAMETER } from './protected-writes.js';
+import { AGENT_LABEL } from './settings.js';
+export const QUESTION_SUMMARY_MAX = 160;
+export const CONTEXT_MAX = 500;
+export const ACTION_MAX = 500;
+export const ACTION_BODY_MAX = 4000;
+export const TOOL_TARGET_MAX = 80;
+export const TOOL_NAME_MAX = 100;
+export const APPROVAL_TITLE_MAX = 80;
+export const APPROVAL_DESCRIPTION_MAX = 512;
+const COMMAND_PARAMETERS = ['command', 'code'];
+const WORKDIR_PARAMETER = 'workdir';
+const TARGET_WORDS = 2;
+const ELLIPSIS = '…';
+const collapsed = (text) => text.split(/\s+/).filter(Boolean).join(' ');
+export const truncated = (text, max) => text.length <= max ? text : `${text.slice(0, max - ELLIPSIS.length)}${ELLIPSIS}`;
+const stringParameter = (params, name) => {
+    const value = params[name];
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+};
+const commandOf = (event) => COMMAND_PARAMETERS.map(name => stringParameter(event.params, name)).find(value => value !== undefined);
+const serializedParams = (params) => {
+    try {
+        return JSON.stringify(params) ?? '';
+    }
+    catch {
+        return '';
+    }
+};
+const questionFor = (toolName, summary, command, folder) => {
+    if (command !== undefined)
+        return `Allow ${AGENT_LABEL} to run \`${summary}\`?`;
+    if (folder !== undefined)
+        return `Allow ${AGENT_LABEL} to start a session in \`${truncated(collapsed(folder), QUESTION_SUMMARY_MAX)}\`?`;
+    return `Allow ${AGENT_LABEL} to use ${toolName}${summary ? `: \`${summary}\`` : ''}?`;
+};
+const contextLines = (event, agentName) => {
+    const workdir = stringParameter(event.params, WORKDIR_PARAMETER) ?? stringParameter(event.params, SPAWN_FOLDER_PARAMETER);
+    return [
+        `${agentName} wants to use its ${event.toolName} tool.`,
+        ...(workdir ? [`Working directory: ${workdir}`] : []),
+        ...(event.params.elevated === true ? ['It asked for elevated mode, outside the sandbox.'] : []),
+    ];
+};
+const targetOf = (command) => {
+    if (command === undefined)
+        return undefined;
+    const head = collapsed(command).split(' ').slice(0, TARGET_WORDS).join(' ');
+    return head ? truncated(head, TOOL_TARGET_MAX) : undefined;
+};
+export const approvalQuestionFor = (event, agentName) => {
+    const toolName = truncated(event.toolName.trim(), TOOL_NAME_MAX);
+    const command = commandOf(event);
+    const raw = command ?? serializedParams(event.params);
+    const body = redactSecrets(raw);
+    const summary = truncated(collapsed(body), QUESTION_SUMMARY_MAX);
+    return {
+        question: questionFor(toolName, summary, command, event.toolName === SESSIONS_SPAWN_TOOL ? stringParameter(event.params, SPAWN_FOLDER_PARAMETER) : undefined),
+        context: truncated(redactSecrets(contextLines(event, agentName).join(' ')), CONTEXT_MAX),
+        toolName,
+        toolTarget: targetOf(command === undefined ? undefined : body),
+        action: truncated(collapsed(body), ACTION_MAX),
+        actionBody: truncated(redactSecretsDeep(raw), ACTION_BODY_MAX),
+    };
+};

package/dist/connection.d.ts

@@ -0,0 +1,26 @@
+export declare const API_KEY_VARIABLE = "PUSHARY_API_KEY";
+export declare const BASE_URL_VARIABLE = "PUSHARY_BASE_URL";
+export declare const CONFIG_FILE_VARIABLE = "PUSHARY_CONFIG_FILE";
+export declare const DEFAULT_BASE_URL = "https://pushary.com";
+export type Environment = Readonly<Record<string, string | undefined>>;
+export interface PusharyConnection {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly machineId: string | null;
+}
+export type ConnectionReading = {
+    readonly kind: 'ready';
+    readonly connection: PusharyConnection;
+} | {
+    readonly kind: 'missing_api_key';
+} | {
+    readonly kind: 'invalid_base_url';
+};
+export interface ConnectionSources {
+    readonly environment: Environment;
+    readonly homeDirectory: string;
+    readonly readText: (path: string) => string | null;
+    readonly hostName: () => string | null;
+}
+export declare const readPusharyConnection: (sources: ConnectionSources) => ConnectionReading;
+export declare const processConnectionSources: () => ConnectionSources;

package/dist/connection.js

@@ -0,0 +1,101 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { isValidApiKey } from './api-key-shape.js';
+import { isPusharyHost } from './pushary-hosts.js';
+export const API_KEY_VARIABLE = 'PUSHARY_API_KEY';
+export const BASE_URL_VARIABLE = 'PUSHARY_BASE_URL';
+export const CONFIG_FILE_VARIABLE = 'PUSHARY_CONFIG_FILE';
+export const DEFAULT_BASE_URL = 'https://pushary.com';
+const PUSHARY_DIRECTORY = '.pushary';
+const PUSHARY_CONFIG_FILE = 'config.json';
+const SHARED_MACHINE_ID_FILE = 'machine-id';
+const SHARED_MACHINE_ID_PATTERN = /^[A-Za-z0-9-]{1,128}$/;
+const HOSTNAME_MACHINE_ID_LENGTH = 8;
+const PUSHARY_PROTOCOL = 'https:';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const parsedJson = (text) => {
+    if (text === null)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+};
+const usableApiKey = (value) => {
+    if (typeof value !== 'string')
+        return null;
+    const key = value.trim();
+    return isValidApiKey(key) ? key : null;
+};
+const pusharyPath = (sources, file) => join(sources.homeDirectory, PUSHARY_DIRECTORY, file);
+const configFilePath = (sources) => {
+    const configured = sources.environment[CONFIG_FILE_VARIABLE]?.trim();
+    return configured ? configured : pusharyPath(sources, PUSHARY_CONFIG_FILE);
+};
+const apiKeyFrom = (sources) => {
+    const fromEnvironment = usableApiKey(sources.environment[API_KEY_VARIABLE]);
+    if (fromEnvironment !== null)
+        return fromEnvironment;
+    const config = parsedJson(sources.readText(configFilePath(sources)));
+    return isRecord(config) ? usableApiKey(config.apiKey) : null;
+};
+const isPusharyOrigin = (url) => url.protocol === PUSHARY_PROTOCOL
+    && url.port === ''
+    && url.username === ''
+    && url.password === ''
+    && isPusharyHost(url.hostname);
+const baseUrlFrom = (environment) => {
+    const configured = environment[BASE_URL_VARIABLE]?.trim();
+    if (!configured)
+        return DEFAULT_BASE_URL;
+    try {
+        const url = new URL(configured);
+        return isPusharyOrigin(url) ? url.origin : null;
+    }
+    catch {
+        return null;
+    }
+};
+const hostnameMachineId = (sources) => {
+    const host = sources.hostName();
+    return host ? createHash('sha256').update(host, 'utf8').digest('hex').slice(0, HOSTNAME_MACHINE_ID_LENGTH) : null;
+};
+const machineIdFrom = (sources) => {
+    const shared = sources.readText(pusharyPath(sources, SHARED_MACHINE_ID_FILE))?.trim() ?? '';
+    return SHARED_MACHINE_ID_PATTERN.test(shared) ? shared : hostnameMachineId(sources);
+};
+export const readPusharyConnection = (sources) => {
+    const baseUrl = baseUrlFrom(sources.environment);
+    if (baseUrl === null)
+        return { kind: 'invalid_base_url' };
+    const apiKey = apiKeyFrom(sources);
+    if (apiKey === null)
+        return { kind: 'missing_api_key' };
+    return { kind: 'ready', connection: { baseUrl, apiKey, machineId: machineIdFrom(sources) } };
+};
+const readTextFile = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+const currentHostName = () => {
+    try {
+        return hostname() || null;
+    }
+    catch {
+        return null;
+    }
+};
+export const processConnectionSources = () => ({
+    environment: process.env,
+    homeDirectory: homedir(),
+    readText: readTextFile,
+    hostName: currentHostName,
+});

package/dist/decision-reply.d.ts

@@ -0,0 +1,9 @@
+export declare const APPROVE_ANSWER = "yes";
+export declare const STOP_HANDOFF_ACTION = "stop";
+export declare const DECISION_STOP_STATUSES: readonly string[];
+export interface DecisionStopFields {
+    readonly status?: unknown;
+    readonly handoffAction?: unknown;
+}
+export declare const isDecisionStoppedReply: (reply: DecisionStopFields) => boolean;
+export declare const isApprovingAnswer: (answer: string) => boolean;

package/dist/decision-reply.js

@@ -0,0 +1,6 @@
+// Generated by scripts/generate-editor-redaction.mjs.
+export const APPROVE_ANSWER = 'yes';
+export const STOP_HANDOFF_ACTION = 'stop';
+export const DECISION_STOP_STATUSES = ['cancelled', 'unavailable', 'stopped', 'missing'];
+export const isDecisionStoppedReply = (reply) => reply.handoffAction === STOP_HANDOFF_ACTION || (typeof reply.status === 'string' && DECISION_STOP_STATUSES.includes(reply.status));
+export const isApprovingAnswer = (answer) => answer === APPROVE_ANSWER;

package/dist/gate-result.d.ts

@@ -0,0 +1,13 @@
+import { type ApprovalQuestion } from './approval-question.js';
+import { type ConnectionReading } from './connection.js';
+import type { GateOutcome } from './gate.js';
+import type { OpenClawApprovalDecision, OpenClawBeforeToolCallResult } from './host-api.js';
+export declare const SETUP_COMMAND = "npx pushary@latest setup";
+export declare const DEVICES_URL = "https://pushary.com/dashboard/agent/settings";
+export declare const HAND_BACK_DECISIONS: readonly OpenClawApprovalDecision[];
+export type ConnectionProblem = Exclude<ConnectionReading, {
+    readonly kind: 'ready';
+}>['kind'];
+export type HandBackSurface = 'openclaw_prompt' | 'none';
+export declare const openClawResultFor: (outcome: GateOutcome, question: ApprovalQuestion, handBackSurface: HandBackSurface) => OpenClawBeforeToolCallResult | undefined;
+export declare const notConnectedResultFor: (problem: ConnectionProblem, toolName: string) => OpenClawBeforeToolCallResult;

package/dist/gate-result.js

@@ -0,0 +1,58 @@
+import { APPROVAL_DESCRIPTION_MAX, APPROVAL_TITLE_MAX, truncated } from './approval-question.js';
+import { API_KEY_VARIABLE, BASE_URL_VARIABLE } from './connection.js';
+import { MIN_HOST_VERSION } from './host-version.js';
+export const SETUP_COMMAND = 'npx pushary@latest setup';
+export const DEVICES_URL = 'https://pushary.com/dashboard/agent/settings';
+export const HAND_BACK_DECISIONS = ['allow-once', 'deny'];
+const SECONDS_PER_MINUTE = 60;
+const MILLISECONDS_PER_SECOND = 1_000;
+const blocked = (blockReason) => ({ block: true, blockReason });
+const waitedFor = (heldMs) => {
+    const seconds = Math.round(heldMs / MILLISECONDS_PER_SECOND);
+    if (seconds < SECONDS_PER_MINUTE)
+        return `${seconds} seconds`;
+    const minutes = Math.round(seconds / SECONDS_PER_MINUTE);
+    return minutes === 1 ? '1 minute' : `${minutes} minutes`;
+};
+const unavailableReason = (toolName, outcome) => {
+    if (outcome.failure === 'unauthorized') {
+        return `Pushary rejected the API key, so this ${toolName} call was blocked. Nothing ran. Run ${SETUP_COMMAND} again to get a new key, then restart the OpenClaw gateway.`;
+    }
+    if (outcome.failure === 'tool_error' || outcome.failure === 'refused') {
+        return `Pushary refused the approval request, so this ${toolName} call was blocked. Nothing ran. Answer or cancel your open questions in Pushary, then try again.`;
+    }
+    return `Pushary could not be reached, so nobody could approve this ${toolName} call and it was blocked. Nothing ran. Try again in a moment.`;
+};
+const handedBack = (question) => ({
+    requireApproval: {
+        title: truncated(question.question, APPROVAL_TITLE_MAX),
+        description: truncated(`${question.context} ${question.action}`, APPROVAL_DESCRIPTION_MAX),
+        severity: 'warning',
+        allowedDecisions: [...HAND_BACK_DECISIONS],
+    },
+});
+const noPromptToHandBackTo = (toolName) => blocked(`Your Pushary delivery mode keeps this approval off your phone, and this OpenClaw is older than ${MIN_HOST_VERSION}, so it cannot ask in its own prompt. This ${toolName} call was blocked. Update OpenClaw, or change the delivery mode in Pushary.`);
+export const openClawResultFor = (outcome, question, handBackSurface) => {
+    const tool = question.toolName;
+    switch (outcome.kind) {
+        case 'approved':
+            return undefined;
+        case 'denied':
+            return blocked(`The person you asked in Pushary did not approve this ${tool} call, so it was blocked. Do not retry it. Ask them what to do instead.`);
+        case 'unanswered':
+            return blocked(`Nobody answered the Pushary approval within ${waitedFor(outcome.heldMs)}, so this ${tool} call was blocked. Nothing ran.`);
+        case 'stopped':
+            return blocked(`Pushary stopped this request, so this ${tool} call was blocked. Stop and wait for instructions.`);
+        case 'cancelled':
+            return blocked(`This ${tool} call was cancelled before anyone answered the Pushary approval. Nothing ran.`);
+        case 'undeliverable':
+            return blocked(`No phone, browser or Slack is connected to Pushary, so nobody could approve this ${tool} call and it was blocked. Connect one at ${DEVICES_URL}.`);
+        case 'handed_back':
+            return handBackSurface === 'openclaw_prompt' ? handedBack(question) : noPromptToHandBackTo(tool);
+        case 'unavailable':
+            return blocked(unavailableReason(tool, outcome));
+    }
+};
+export const notConnectedResultFor = (problem, toolName) => problem === 'missing_api_key'
+    ? blocked(`Pushary is not set up for OpenClaw on this machine: ${API_KEY_VARIABLE} is missing, so this ${toolName} call was blocked. Run ${SETUP_COMMAND}, or add ${API_KEY_VARIABLE} to ~/.openclaw/.env, then restart the OpenClaw gateway.`)
+    : blocked(`${BASE_URL_VARIABLE} is not https://pushary.com or https://www.pushary.com, so this ${toolName} call was blocked. Remove it, then restart the OpenClaw gateway.`);

package/dist/gate.d.ts

@@ -0,0 +1,49 @@
+import type { ApprovalQuestion } from './approval-question.js';
+import { type CallFailure, type PusharyQuestions } from './pushary-client.js';
+export declare const ASK_ATTEMPTS = 3;
+export declare const ASK_RETRY_PAUSE_MS = 1000;
+export declare const POLL_RETRY_PAUSES_MS: readonly [number, ...number[]];
+export declare const UNANSWERED_POLL_PAUSE_MS = 2000;
+export declare const LATE_ANSWER_POLL_MS = 1000;
+export declare const WITHDRAW_ATTEMPTS = 3;
+export declare const WITHDRAW_RETRY_PAUSE_MS = 500;
+export type GateFailure = CallFailure | 'unreadable_reply';
+export type GateOutcome = {
+    readonly kind: 'approved';
+} | {
+    readonly kind: 'denied';
+} | {
+    readonly kind: 'unanswered';
+    readonly heldMs: number;
+} | {
+    readonly kind: 'stopped';
+} | {
+    readonly kind: 'cancelled';
+} | {
+    readonly kind: 'undeliverable';
+} | {
+    readonly kind: 'handed_back';
+} | {
+    readonly kind: 'unavailable';
+    readonly failure: GateFailure;
+};
+export interface GateClock {
+    readonly monotonicMs: () => number;
+    readonly wallMs: () => number;
+    readonly sleep: (ms: number, signal: AbortSignal | undefined) => Promise<void>;
+}
+export interface GateRequest {
+    readonly question: ApprovalQuestion;
+    readonly agentName: string;
+    readonly requestId: string;
+    readonly holdMs: number;
+    readonly withdrawReserveMs: number;
+    readonly sessionId?: string;
+    readonly machineId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface GateDependencies {
+    readonly questions: PusharyQuestions;
+    readonly clock: GateClock;
+}
+export declare const runApprovalGate: (request: GateRequest, dependencies: GateDependencies) => Promise<GateOutcome>;