@pushary/openclaw 0.0.0-stage → 0.1.0

package/dist/gate.js

@@ -0,0 +1,173 @@
+import { CANCEL_REQUEST_TIMEOUT_MS, POLL_RESPONSE_GRACE_MS, } from './pushary-client.js';
+import { askReplyOf, isExplicitApproval, questionStateOf, withdrawalOf } from './replies.js';
+export const ASK_ATTEMPTS = 3;
+export const ASK_RETRY_PAUSE_MS = 1_000;
+export const POLL_RETRY_PAUSES_MS = [2_000, 4_000, 8_000, 15_000];
+export const UNANSWERED_POLL_PAUSE_MS = 2_000;
+export const LATE_ANSWER_POLL_MS = 1_000;
+export const WITHDRAW_ATTEMPTS = 3;
+export const WITHDRAW_RETRY_PAUSE_MS = 500;
+const RETRYABLE_FAILURES = new Set(['network', 'timed_out', 'server_error']);
+const LATE_ANSWER_REQUEST_MS = LATE_ANSWER_POLL_MS + POLL_RESPONSE_GRACE_MS;
+const decisionFor = (answer) => isExplicitApproval(answer) ? { kind: 'approved' } : { kind: 'denied' };
+const askArgumentsFor = (request, waitEndsAt) => ({
+    question: request.question.question,
+    type: 'confirm',
+    wait: false,
+    context: request.question.context,
+    agentName: request.agentName,
+    toolName: request.question.toolName,
+    action: request.question.action,
+    actionBody: request.question.actionBody,
+    waitEndsAt,
+    localSurfaceAvailable: false,
+    requestId: request.requestId,
+    ...(request.question.toolTarget === undefined ? {} : { toolTarget: request.question.toolTarget }),
+    ...(request.sessionId === undefined ? {} : { sessionId: request.sessionId }),
+    ...(request.machineId === undefined ? {} : { machineId: request.machineId }),
+});
+const isRetryable = (failure) => RETRYABLE_FAILURES.has(failure);
+const pollFailureOf = (polled, state) => {
+    if (polled.kind === 'failed')
+        return polled.failure;
+    return state?.kind === 'unreadable' ? 'unreadable_reply' : null;
+};
+const retryPauseMs = (consecutiveFailures) => POLL_RETRY_PAUSES_MS[Math.min(consecutiveFailures, POLL_RETRY_PAUSES_MS.length) - 1] ?? POLL_RETRY_PAUSES_MS[0];
+const pauseAfterPoll = (consecutiveFailures) => consecutiveFailures > 0 ? retryPauseMs(consecutiveFailures) : UNANSWERED_POLL_PAUSE_MS;
+const isAbortFailure = (result) => result.kind === 'failed' && result.failure === 'aborted';
+const isSettled = (state) => state !== null && state.kind !== 'pending' && state.kind !== 'unreadable';
+const withdrawalOfResult = (result) => (result.kind === 'reply' ? withdrawalOf(result.value) : 'unreachable');
+const WITHDRAW_RETRY_NEEDS_MS = WITHDRAW_RETRY_PAUSE_MS + CANCEL_REQUEST_TIMEOUT_MS;
+const mayRetryWithdrawal = (result, attempt, remainingMs) => result.kind === 'failed' && isRetryable(result.failure) && attempt < WITHDRAW_ATTEMPTS && remainingMs >= WITHDRAW_RETRY_NEEDS_MS;
+export const runApprovalGate = async (request, dependencies) => {
+    const { questions, clock } = dependencies;
+    const startedAt = clock.monotonicMs();
+    const deadline = startedAt + request.holdMs;
+    const hookDeadline = deadline + request.withdrawReserveMs;
+    const aborted = () => request.signal?.aborted === true;
+    const remainingMs = (until) => until - clock.monotonicMs();
+    const heldMs = () => Math.max(0, clock.monotonicMs() - startedAt);
+    const cancelWithRetry = async (correlationId, endsAt) => {
+        for (let attempt = 1;; attempt += 1) {
+            const result = await questions.cancel(correlationId);
+            const withdrawal = withdrawalOfResult(result);
+            if (withdrawal !== 'unreachable' || !mayRetryWithdrawal(result, attempt, remainingMs(endsAt)))
+                return withdrawal;
+            await clock.sleep(WITHDRAW_RETRY_PAUSE_MS, undefined);
+        }
+    };
+    const lateAnswerOf = async (correlationId, endsAt) => {
+        if (remainingMs(endsAt) < LATE_ANSWER_REQUEST_MS)
+            return { kind: 'gone' };
+        const late = await questions.waitForAnswer(correlationId, LATE_ANSWER_POLL_MS, undefined);
+        const state = late.kind === 'reply' ? questionStateOf(late.value) : null;
+        if (state?.kind === 'stopped')
+            return { kind: 'stop' };
+        return state?.kind === 'answered' ? { kind: 'answered', value: state.value } : { kind: 'gone' };
+    };
+    const withdraw = async (correlationId) => {
+        const endsAt = Math.min(hookDeadline, clock.monotonicMs() + request.withdrawReserveMs);
+        const withdrawal = await cancelWithRetry(correlationId, endsAt);
+        if (withdrawal === 'not_pending')
+            return lateAnswerOf(correlationId, endsAt);
+        return { kind: withdrawal };
+    };
+    const cancelledAfterWithdrawing = async (correlationId) => {
+        await withdraw(correlationId);
+        return { kind: 'cancelled' };
+    };
+    const unavailableAfterWithdrawing = async (correlationId, failure) => {
+        await withdraw(correlationId);
+        return { kind: 'unavailable', failure };
+    };
+    const handBack = async (correlationId, reason) => {
+        const withdrawn = await withdraw(correlationId);
+        if (withdrawn.kind === 'answered')
+            return decisionFor(withdrawn.value);
+        if (withdrawn.kind === 'stop')
+            return { kind: 'stopped' };
+        if (withdrawn.kind === 'unreachable')
+            return { kind: 'unavailable', failure: 'network' };
+        return reason === 'no_devices' ? { kind: 'undeliverable' } : { kind: 'handed_back' };
+    };
+    const createQuestion = async () => {
+        const args = askArgumentsFor(request, new Date(clock.wallMs() + request.holdMs).toISOString());
+        let last = { kind: 'failed', failure: 'network' };
+        for (let attempt = 0; attempt < ASK_ATTEMPTS && remainingMs(deadline) > 0; attempt += 1) {
+            if (attempt > 0) {
+                if (aborted())
+                    return last;
+                await clock.sleep(Math.min(ASK_RETRY_PAUSE_MS, remainingMs(deadline)), request.signal);
+            }
+            last = await questions.ask(args);
+            if (last.kind === 'reply' || !isRetryable(last.failure))
+                return last;
+        }
+        return last;
+    };
+    const settleAfterHold = async (correlationId, handBackAt, lastFailure) => {
+        const handBackDue = handBackAt !== null && handBackAt < deadline && clock.monotonicMs() >= handBackAt;
+        const withdrawn = await withdraw(correlationId);
+        if (withdrawn.kind === 'answered')
+            return decisionFor(withdrawn.value);
+        if (withdrawn.kind === 'stop')
+            return { kind: 'stopped' };
+        if (withdrawn.kind === 'unreachable')
+            return { kind: 'unavailable', failure: lastFailure ?? 'network' };
+        if (handBackDue)
+            return { kind: 'handed_back' };
+        if (lastFailure !== null)
+            return { kind: 'unavailable', failure: lastFailure };
+        return { kind: 'unanswered', heldMs: heldMs() };
+    };
+    const settleState = async (correlationId, state) => {
+        if (state.kind === 'answered')
+            return decisionFor(state.value);
+        if (state.kind === 'stopped')
+            return { kind: 'stopped' };
+        if (state.kind === 'ended')
+            return { kind: 'unanswered', heldMs: heldMs() };
+        return handBack(correlationId, state.reason);
+    };
+    const waitForDecision = async (correlationId, handBackAfterMs) => {
+        const handBackAt = handBackAfterMs === null ? null : startedAt + handBackAfterMs;
+        const until = handBackAt === null ? deadline : Math.min(deadline, handBackAt);
+        let lastFailure = null;
+        let consecutiveFailures = 0;
+        while (remainingMs(until) > 0) {
+            if (aborted())
+                return cancelledAfterWithdrawing(correlationId);
+            const polled = await questions.waitForAnswer(correlationId, remainingMs(until), request.signal);
+            if (aborted() || isAbortFailure(polled))
+                return cancelledAfterWithdrawing(correlationId);
+            const state = polled.kind === 'reply' ? questionStateOf(polled.value) : null;
+            if (isSettled(state))
+                return settleState(correlationId, state);
+            lastFailure = pollFailureOf(polled, state);
+            if (lastFailure !== null && !isRetryable(lastFailure))
+                return unavailableAfterWithdrawing(correlationId, lastFailure);
+            consecutiveFailures = lastFailure === null ? 0 : consecutiveFailures + 1;
+            await clock.sleep(Math.min(pauseAfterPoll(consecutiveFailures), Math.max(0, remainingMs(until))), request.signal);
+        }
+        if (aborted())
+            return cancelledAfterWithdrawing(correlationId);
+        return settleAfterHold(correlationId, handBackAt, lastFailure);
+    };
+    if (aborted())
+        return { kind: 'cancelled' };
+    const created = await createQuestion();
+    const reply = created.kind === 'reply' ? askReplyOf(created.value) : null;
+    if (aborted())
+        return reply?.kind === 'question' ? cancelledAfterWithdrawing(reply.correlationId) : { kind: 'cancelled' };
+    if (created.kind === 'failed')
+        return { kind: 'unavailable', failure: created.failure };
+    if (reply === null || reply.kind === 'unreadable')
+        return { kind: 'unavailable', failure: 'unreadable_reply' };
+    if (reply.kind === 'stopped')
+        return { kind: 'stopped' };
+    if (reply.state.kind === 'pending')
+        return waitForDecision(reply.correlationId, reply.handBackAfterMs);
+    if (reply.state.kind === 'unreadable')
+        return unavailableAfterWithdrawing(reply.correlationId, 'unreadable_reply');
+    return settleState(reply.correlationId, reply.state);
+};

package/dist/hook-budget.d.ts

@@ -0,0 +1,10 @@
+export declare const REQUESTED_HOOK_TIMEOUT_MS = 300000;
+export declare const WITHDRAW_RESERVE_MS = 10000;
+export declare const OPERATOR_HOOK_TIMEOUT_MAX_MS = 600000;
+export type HookBudgetSource = 'plugin' | 'operator_hook_timeout' | 'operator_plugin_timeout';
+export interface HookBudget {
+    readonly timeoutMs: number;
+    readonly source: HookBudgetSource;
+}
+export declare const hookBudgetFrom: (hostConfig: unknown, pluginId: string) => HookBudget;
+export declare const holdMsWithin: (hookTimeoutMs: number) => number;

package/dist/hook-budget.js

@@ -0,0 +1,19 @@
+import { BEFORE_TOOL_CALL_HOOK } from './host-api.js';
+export const REQUESTED_HOOK_TIMEOUT_MS = 300_000;
+export const WITHDRAW_RESERVE_MS = 10_000;
+export const OPERATOR_HOOK_TIMEOUT_MAX_MS = 600_000;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const fieldOf = (value, key) => (isRecord(value) ? value[key] : undefined);
+const operatorMilliseconds = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 && value <= OPERATOR_HOOK_TIMEOUT_MAX_MS ? value : null;
+const hookPolicyOf = (hostConfig, pluginId) => fieldOf(fieldOf(fieldOf(fieldOf(hostConfig, 'plugins'), 'entries'), pluginId), 'hooks');
+export const hookBudgetFrom = (hostConfig, pluginId) => {
+    const policy = hookPolicyOf(hostConfig, pluginId);
+    const perHook = operatorMilliseconds(fieldOf(fieldOf(policy, 'timeouts'), BEFORE_TOOL_CALL_HOOK));
+    if (perHook !== null)
+        return { timeoutMs: perHook, source: 'operator_hook_timeout' };
+    const perPlugin = operatorMilliseconds(fieldOf(policy, 'timeoutMs'));
+    if (perPlugin !== null)
+        return { timeoutMs: perPlugin, source: 'operator_plugin_timeout' };
+    return { timeoutMs: REQUESTED_HOOK_TIMEOUT_MS, source: 'plugin' };
+};
+export const holdMsWithin = (hookTimeoutMs) => Math.max(hookTimeoutMs - WITHDRAW_RESERVE_MS, Math.floor(hookTimeoutMs / 2));

package/dist/host-api.d.ts

@@ -0,0 +1,60 @@
+export declare const BEFORE_TOOL_CALL_HOOK = "before_tool_call";
+export type OpenClawApprovalDecision = 'allow-once' | 'allow-always' | 'deny';
+export type OpenClawApprovalSeverity = 'info' | 'warning' | 'critical';
+export type OpenClawToolMatcher = readonly [string, ...string[]];
+export interface OpenClawBeforeToolCallEvent {
+    readonly toolName: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly toolKind?: string;
+    readonly toolInputKind?: string;
+    readonly runId?: string;
+    readonly toolCallId?: string;
+    readonly derivedPaths?: readonly string[];
+}
+export interface OpenClawToolContext {
+    readonly agentId?: string;
+    readonly sessionKey?: string;
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly toolCallId?: string;
+    readonly channelId?: string;
+    readonly abortSignal?: AbortSignal;
+}
+export interface OpenClawApprovalRequest {
+    title: string;
+    description: string;
+    severity?: OpenClawApprovalSeverity;
+    timeoutMs?: number;
+    timeoutReason?: string;
+    allowedDecisions?: OpenClawApprovalDecision[];
+}
+export interface OpenClawBeforeToolCallResult {
+    block?: boolean;
+    blockReason?: string;
+    requireApproval?: OpenClawApprovalRequest;
+}
+export type OpenClawBeforeToolCallHandler = (event: OpenClawBeforeToolCallEvent, context: OpenClawToolContext) => Promise<OpenClawBeforeToolCallResult | undefined>;
+export interface OpenClawHookOptions {
+    readonly matcher?: OpenClawToolMatcher;
+    readonly priority?: number;
+    readonly timeoutMs?: number;
+}
+export interface OpenClawLogger {
+    readonly info: (message: string) => void;
+    readonly warn: (message: string) => void;
+    readonly error: (message: string) => void;
+}
+export interface OpenClawPluginApi {
+    readonly id: string;
+    readonly config: unknown;
+    readonly pluginConfig?: unknown;
+    readonly runtime?: unknown;
+    readonly logger: OpenClawLogger;
+    readonly on: (hookName: typeof BEFORE_TOOL_CALL_HOOK, handler: OpenClawBeforeToolCallHandler, options?: OpenClawHookOptions) => void;
+}
+export interface OpenClawPluginEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly register: (api: OpenClawPluginApi) => void;
+}

package/dist/host-api.js

@@ -0,0 +1 @@
+export const BEFORE_TOOL_CALL_HOOK = 'before_tool_call';

package/dist/host-version.d.ts

@@ -0,0 +1,12 @@
+export declare const MIN_HOST_VERSION = "2026.11.3";
+export type HostSupport = {
+    readonly kind: 'supported';
+    readonly version: string;
+} | {
+    readonly kind: 'too_old';
+    readonly version: string;
+} | {
+    readonly kind: 'unknown';
+};
+export declare const hostSupportFrom: (runtime: unknown) => HostSupport;
+export declare const handsBackToTheHost: (support: HostSupport) => boolean;

package/dist/host-version.js

@@ -0,0 +1,25 @@
+export const MIN_HOST_VERSION = '2026.11.3';
+const RELEASE_VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?$/;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const releaseVersionOf = (text) => {
+    const match = RELEASE_VERSION_PATTERN.exec(text.trim());
+    if (match === null)
+        return null;
+    const [, major, minor, patch, prerelease] = match;
+    return { parts: [Number(major), Number(minor), Number(patch)], prerelease: prerelease !== undefined };
+};
+const isAtLeast = (version, floor) => {
+    const differing = version.parts.findIndex((part, index) => part !== floor.parts[index]);
+    if (differing === -1)
+        return !version.prerelease || floor.prerelease;
+    return (version.parts[differing] ?? 0) > (floor.parts[differing] ?? 0);
+};
+const FLOOR = releaseVersionOf(MIN_HOST_VERSION);
+export const hostSupportFrom = (runtime) => {
+    const version = isRecord(runtime) && typeof runtime.version === 'string' ? runtime.version : null;
+    const parsed = version === null ? null : releaseVersionOf(version);
+    if (version === null || parsed === null || FLOOR === null)
+        return { kind: 'unknown' };
+    return isAtLeast(parsed, FLOOR) ? { kind: 'supported', version } : { kind: 'too_old', version };
+};
+export const handsBackToTheHost = (support) => support.kind === 'supported';

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { type GateEnvironment } from './approval-hook.js';
+import type { GateClock } from './gate.js';
+import type { OpenClawPluginEntry } from './host-api.js';
+export declare const systemClock: GateClock;
+export declare const processGateEnvironment: () => GateEnvironment;
+declare const pusharyPlugin: OpenClawPluginEntry;
+export default pusharyPlugin;

package/dist/index.js

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { registerApprovalGate } from './approval-hook.js';
+import { processConnectionSources, readPusharyConnection } from './connection.js';
+import { createPusharyQuestions } from './pushary-client.js';
+import { PLUGIN_DESCRIPTION, PLUGIN_ID, PLUGIN_NAME } from './settings.js';
+const sleepUnlessAborted = async (ms, signal) => {
+    try {
+        await delay(ms, undefined, signal === undefined ? undefined : { signal });
+    }
+    catch {
+        return;
+    }
+};
+export const systemClock = {
+    monotonicMs: () => performance.now(),
+    wallMs: () => Date.now(),
+    sleep: sleepUnlessAborted,
+};
+export const processGateEnvironment = () => ({
+    readConnection: () => readPusharyConnection(processConnectionSources()),
+    questionsFor: connection => createPusharyQuestions(connection),
+    clock: systemClock,
+    newRequestId: randomUUID,
+});
+const pusharyPlugin = {
+    id: PLUGIN_ID,
+    name: PLUGIN_NAME,
+    description: PLUGIN_DESCRIPTION,
+    register: api => registerApprovalGate(api, processGateEnvironment()),
+};
+export default pusharyPlugin;

package/dist/openclaw-paths.d.ts

@@ -0,0 +1,14 @@
+export declare const OPENCLAW_ENVIRONMENT_KEYS: readonly ["OPENCLAW_HOME", "OPENCLAW_STATE_DIR", "OPENCLAW_CONFIG_PATH", "OPENCLAW_PROFILE"];
+export type OpenClawEnvironmentKey = (typeof OPENCLAW_ENVIRONMENT_KEYS)[number];
+export type OpenClawEnvironment = Readonly<Partial<Record<OpenClawEnvironmentKey, string>>>;
+export interface OpenClawPaths {
+    readonly home: string;
+    readonly stateDirectory: string;
+    readonly configFile: string;
+    readonly environmentFile: string;
+}
+export declare const OWNED_PLUGIN_FOLDER_NAME = "openclaw-plugin";
+export declare const openClawPathsFrom: (environment: OpenClawEnvironment, osHome: string) => OpenClawPaths;
+export declare const openClawDirectoriesToLookIn: (paths: OpenClawPaths) => readonly string[];
+export declare const openClawEnvironmentOf: (environment: Readonly<Record<string, string | undefined>>) => OpenClawEnvironment;
+export declare const ownedPluginFolderIn: (osHome: string) => string;

package/dist/openclaw-paths.js

@@ -0,0 +1,43 @@
+// Generated by scripts/generate-editor-redaction.mjs.
+import { join, resolve } from 'node:path';
+export const OPENCLAW_ENVIRONMENT_KEYS = ['OPENCLAW_HOME', 'OPENCLAW_STATE_DIR', 'OPENCLAW_CONFIG_PATH', 'OPENCLAW_PROFILE'];
+const STATE_DIRECTORY_NAME = '.openclaw';
+const PUSHARY_DIRECTORY_NAME = '.pushary';
+export const OWNED_PLUGIN_FOLDER_NAME = 'openclaw-plugin';
+const CONFIG_FILE_NAME = 'openclaw.json';
+const ENVIRONMENT_FILE_NAME = '.env';
+const UNSET_SPELLINGS = new Set(['undefined', 'null']);
+const HOME_PREFIX = /^~(?=$|[\\/])/;
+const setValue = (value) => {
+    const trimmed = value?.trim();
+    return trimmed && !UNSET_SPELLINGS.has(trimmed) ? trimmed : undefined;
+};
+const expandedFrom = (path, home) => resolve(path.replace(HOME_PREFIX, () => home));
+const homeOf = (environment, osHome) => {
+    const configured = setValue(environment.OPENCLAW_HOME);
+    if (configured === undefined)
+        return resolve(osHome);
+    return HOME_PREFIX.test(configured) ? expandedFrom(configured, osHome) : resolve(configured);
+};
+const pathSetting = (value, home) => {
+    const configured = value?.trim();
+    if (!configured)
+        return undefined;
+    return HOME_PREFIX.test(configured) ? expandedFrom(configured, home) : resolve(configured);
+};
+export const openClawPathsFrom = (environment, osHome) => {
+    const home = homeOf(environment, osHome);
+    const stateDirectory = pathSetting(environment.OPENCLAW_STATE_DIR, home) ?? join(home, STATE_DIRECTORY_NAME);
+    return {
+        home,
+        stateDirectory,
+        configFile: pathSetting(environment.OPENCLAW_CONFIG_PATH, home) ?? join(stateDirectory, CONFIG_FILE_NAME),
+        environmentFile: join(stateDirectory, ENVIRONMENT_FILE_NAME),
+    };
+};
+export const openClawDirectoriesToLookIn = (paths) => [...new Set([paths.stateDirectory, paths.configFile, join(paths.home, STATE_DIRECTORY_NAME)])];
+export const openClawEnvironmentOf = (environment) => Object.fromEntries(OPENCLAW_ENVIRONMENT_KEYS.flatMap(key => {
+    const value = environment[key];
+    return value === undefined ? [] : [[key, value]];
+}));
+export const ownedPluginFolderIn = (osHome) => join(osHome, PUSHARY_DIRECTORY_NAME, OWNED_PLUGIN_FOLDER_NAME);

package/dist/openclaw-write-guard.d.ts

@@ -0,0 +1,5 @@
+import type { OpenClawPluginApi } from './host-api.js';
+import { type FileWriteCall, type OpenClawStateLocations } from './protected-writes.js';
+export declare const stateDirectoryHoldingPlugin: (pluginFile: string) => string | null;
+export declare const openClawStateLocationsFor: (api: OpenClawPluginApi, environment: Readonly<Record<string, string | undefined>>, osHome: string, pluginFile: string, gatewayWorkingDirectory: string) => OpenClawStateLocations;
+export declare const openClawWriteGuardFor: (api: OpenClawPluginApi) => ((call: FileWriteCall) => boolean);

package/dist/openclaw-write-guard.js

@@ -0,0 +1,93 @@
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { openClawEnvironmentOf, openClawPathsFrom, ownedPluginFolderIn } from './openclaw-paths.js';
+import { nodeRealpath, spawnsOutsideTheWorkspace, writesIntoOpenClaw } from './protected-writes.js';
+import { DEFAULT_OPENCLAW_AGENT_ID } from './settings.js';
+const CASE_INSENSITIVE_PLATFORMS = new Set(['darwin', 'win32']);
+const EXTENSIONS_DIRECTORY_NAME = 'extensions';
+const PLUGIN_ROOT_DEPTH = 2;
+const USER_CONFIG_DIRECTORY = '.config';
+const GATEWAY_ENV_FALLBACK_DIRECTORY = 'openclaw';
+const LAUNCHD_LABEL_PREFIX = 'ai.openclaw';
+const SYSTEMD_UNIT_PREFIX = 'openclaw';
+const USER_LAUNCH_AGENTS = ['Library', 'LaunchAgents'];
+const USER_SYSTEMD_UNITS = ['systemd', 'user'];
+const SYSTEM_SERVICE_FILES = [
+    { directory: '/Library/LaunchDaemons', namePrefix: LAUNCHD_LABEL_PREFIX },
+    { directory: '/etc/systemd/system', namePrefix: SYSTEMD_UNIT_PREFIX },
+];
+const GATEWAY_WORKING_ENV_FILE = '.env';
+const LAUNCHD_LABEL_VARIABLE = 'OPENCLAW_LAUNCHD_LABEL';
+const SYSTEMD_UNIT_VARIABLE = 'OPENCLAW_SYSTEMD_UNIT';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const hostFunction = (namespace, name) => {
+    if (!isRecord(namespace))
+        return null;
+    const candidate = namespace[name];
+    return typeof candidate === 'function' ? (...args) => Reflect.apply(candidate, namespace, args) : null;
+};
+const hostPath = (resolver, ...args) => {
+    if (resolver === null)
+        return null;
+    try {
+        const value = resolver(...args);
+        return typeof value === 'string' && value.trim().length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+const runtimeNamespace = (api, name) => (isRecord(api.runtime) ? api.runtime[name] : undefined);
+export const stateDirectoryHoldingPlugin = (pluginFile) => {
+    let pluginRoot = pluginFile;
+    for (let level = 0; level < PLUGIN_ROOT_DEPTH; level += 1)
+        pluginRoot = dirname(pluginRoot);
+    const extensions = dirname(pluginRoot);
+    return basename(extensions) === EXTENSIONS_DIRECTORY_NAME ? dirname(extensions) : null;
+};
+const presentOnly = (paths) => [...new Set(paths.flatMap(path => (path === null ? [] : [path])))];
+export const openClawStateLocationsFor = (api, environment, osHome, pluginFile, gatewayWorkingDirectory) => {
+    const active = openClawPathsFrom(openClawEnvironmentOf(environment), osHome);
+    const persistent = openClawPathsFrom(openClawEnvironmentOf({ OPENCLAW_HOME: environment.OPENCLAW_HOME }), osHome);
+    const hostState = hostPath(hostFunction(runtimeNamespace(api, 'state'), 'resolveStateDir'), environment);
+    const homes = presentOnly([osHome, active.home]);
+    return {
+        stateDirectories: presentOnly([active.stateDirectory, persistent.stateDirectory, hostState, stateDirectoryHoldingPlugin(pluginFile)]),
+        configFiles: presentOnly([active.configFile, persistent.configFile, join(gatewayWorkingDirectory, GATEWAY_WORKING_ENV_FILE)]),
+        protectedTrees: presentOnly([
+            dirname(ownedPluginFolderIn(osHome)),
+            ...homes.map(home => join(home, USER_CONFIG_DIRECTORY, GATEWAY_ENV_FALLBACK_DIRECTORY)),
+        ]),
+        serviceFiles: serviceFilesFor(homes, environment),
+    };
+};
+const overriddenServiceNames = (environment) => presentOnly([environment[LAUNCHD_LABEL_VARIABLE]?.trim() || null, environment[SYSTEMD_UNIT_VARIABLE]?.trim() || null]);
+const serviceFilesFor = (homes, environment) => {
+    const directories = [
+        ...homes.map(home => join(home, ...USER_LAUNCH_AGENTS)),
+        ...homes.map(home => join(home, USER_CONFIG_DIRECTORY, ...USER_SYSTEMD_UNITS)),
+        ...SYSTEM_SERVICE_FILES.map(service => service.directory),
+    ];
+    return [
+        ...homes.flatMap(home => [
+            { directory: join(home, ...USER_LAUNCH_AGENTS), namePrefix: LAUNCHD_LABEL_PREFIX },
+            { directory: join(home, USER_CONFIG_DIRECTORY, ...USER_SYSTEMD_UNITS), namePrefix: SYSTEMD_UNIT_PREFIX },
+        ]),
+        ...SYSTEM_SERVICE_FILES,
+        ...overriddenServiceNames(environment).flatMap(name => directories.map(directory => ({ directory, namePrefix: name }))),
+    ];
+};
+const workspaceFrom = (api) => (agentId) => hostPath(hostFunction(runtimeNamespace(api, 'agent'), 'resolveAgentWorkspaceDir'), api.config, agentId ?? DEFAULT_OPENCLAW_AGENT_ID);
+export const openClawWriteGuardFor = (api) => {
+    const osHome = homedir();
+    const locations = openClawStateLocationsFor(api, process.env, osHome, fileURLToPath(import.meta.url), process.cwd());
+    const system = {
+        osHome,
+        realpath: nodeRealpath,
+        caseInsensitive: CASE_INSENSITIVE_PLATFORMS.has(process.platform),
+        workspaceFor: workspaceFrom(api),
+        otherWorkingDirectories: [process.cwd()],
+    };
+    return call => writesIntoOpenClaw(locations, system, call) || spawnsOutsideTheWorkspace(locations, system, call);
+};

package/dist/protected-writes.d.ts

@@ -0,0 +1,33 @@
+import type { OpenClawBeforeToolCallEvent } from './host-api.js';
+export declare const WRITE_TOOL = "write";
+export declare const EDIT_TOOL = "edit";
+export declare const APPLY_PATCH_TOOL = "apply_patch";
+export declare const FILE_WRITING_TOOLS: readonly string[];
+export interface ServiceFileLocation {
+    readonly directory: string;
+    readonly namePrefix: string;
+}
+export interface OpenClawStateLocations {
+    readonly stateDirectories: readonly string[];
+    readonly configFiles: readonly string[];
+    readonly protectedTrees: readonly string[];
+    readonly serviceFiles: readonly ServiceFileLocation[];
+}
+export interface WriteGuardSystem {
+    readonly osHome: string;
+    readonly realpath: (path: string) => string;
+    readonly caseInsensitive: boolean;
+    readonly workspaceFor: (agentId: string | undefined) => string | null;
+    readonly otherWorkingDirectories: readonly string[];
+}
+export interface FileWriteCall {
+    readonly toolId: string;
+    readonly event: OpenClawBeforeToolCallEvent;
+    readonly agentId: string | undefined;
+}
+export declare const patchTargetsOf: (patch: unknown) => readonly string[];
+export declare const writesIntoOpenClaw: (locations: OpenClawStateLocations, system: WriteGuardSystem, call: FileWriteCall) => boolean;
+export declare const SESSIONS_SPAWN_TOOL = "sessions_spawn";
+export declare const SPAWN_FOLDER_PARAMETER = "cwd";
+export declare const spawnsOutsideTheWorkspace: (locations: OpenClawStateLocations, system: WriteGuardSystem, call: FileWriteCall) => boolean;
+export declare const nodeRealpath: (path: string) => string;