@pinet/slack-bridge 0.1.2 → 0.2.0

package/dist/subtree-broker-runtime.js

@@ -0,0 +1,558 @@
+import { execFile } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { dispatchDirectAgentMessage, resolveDirectAgentTarget } from "./broker/agent-messaging.js";
+import { startBroker } from "./broker/index.js";
+import { HEARTBEAT_INTERVAL_MS } from "./broker/client.js";
+import { buildPinetOwnerToken, generateAgentName, normalizeOutgoingPinetControlMessage, resolvePinetMeshAuth, syncBrokerInboxEntries, } from "./helpers.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_SPAWN_REGISTRATION_TIMEOUT_MS = 45_000;
+const SUBTREE_CHILD_EXIT_GRACE_MS = 5_000;
+function sanitizePathSegment(value) {
+    const sanitized = value.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
+    return sanitized || "agent";
+}
+function randomSuffix() {
+    return Math.random().toString(36).slice(2, 8);
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export function buildSubtreeBrokerPaths(stableId) {
+    const rootDir = path.join(os.homedir(), ".pi", "pinet-subtrees", sanitizePathSegment(stableId));
+    return {
+        rootDir,
+        socketPath: path.join(rootDir, "pinet.sock"),
+        dbPath: path.join(rootDir, "pinet-broker.db"),
+        lockPath: path.join(rootDir, "pinet-broker.lock"),
+    };
+}
+function buildSelfAgentId(stableId) {
+    return `subbroker-${sanitizePathSegment(stableId).slice(0, 80)}`;
+}
+function buildChildLaunchEnv(paths, selfAgentId, input = {}) {
+    return {
+        PINET_SOCKET_PATH: paths.socketPath,
+        PINET_BROKER_MANAGED: "1",
+        PINET_PARENT_AGENT_ID: selfAgentId,
+        PINET_ROOT_AGENT_ID: selfAgentId,
+        PINET_SPAWNED_BY_AGENT_ID: selfAgentId,
+        PINET_LAUNCH_SOURCE: "subtree-broker-tmux",
+        ...(input.launchId ? { PINET_LAUNCH_ID: input.launchId } : {}),
+        ...(input.role ? { PINET_SUBTREE_ROLE: input.role } : {}),
+        ...(input.laneId ? { PINET_LANE_ID: input.laneId } : {}),
+        ...(input.tmuxSession ? { PINET_TMUX_SESSION: input.tmuxSession } : {}),
+    };
+}
+function quoteShellValue(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function buildChildLaunchHint(paths, selfAgentId, cwd) {
+    const env = buildChildLaunchEnv(paths, selfAgentId);
+    const envPrefix = Object.entries(env)
+        .map(([key, value]) => `${key}=${quoteShellValue(value)}`)
+        .join(" ");
+    return `cd ${quoteShellValue(cwd)} && ${envPrefix} pi`;
+}
+function toFollowerInboxEntry(input) {
+    return {
+        inboxId: input.entry.id,
+        message: {
+            threadId: input.message.threadId,
+            source: input.message.source,
+            sender: input.message.sender,
+            body: input.message.body,
+            createdAt: input.message.createdAt,
+            metadata: input.message.metadata,
+        },
+    };
+}
+function metadataString(metadata, key) {
+    const value = metadata?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function resolveRepoPath(repo, cwd) {
+    const trimmed = repo.trim();
+    if (!trimmed)
+        throw new Error("spawn requires repo");
+    const candidates = [
+        path.isAbsolute(trimmed) ? trimmed : null,
+        trimmed === "." ? cwd : null,
+        path.resolve(cwd, trimmed),
+        path.join(os.homedir(), trimmed),
+    ].filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        try {
+            if (fs.statSync(candidate).isDirectory())
+                return candidate;
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    throw new Error(`spawn repo not found: ${repo}`);
+}
+function normalizeRole(role) {
+    const normalized = role?.trim();
+    return normalized && normalized.length > 0 ? normalized : "subworker";
+}
+function buildTmuxSessionName(repoPath, role, launchId) {
+    const repoName = sanitizePathSegment(path.basename(repoPath));
+    const roleName = sanitizePathSegment(role);
+    const shortLaunch = sanitizePathSegment(launchId).slice(-8);
+    return sanitizePathSegment(`pinet-${repoName}-${roleName}-${shortLaunch}`).slice(0, 80);
+}
+function findTmuxSocketPath() {
+    const configuredDir = process.env.CLAUDE_TMUX_SOCKET_DIR?.trim();
+    const candidates = [
+        configuredDir ? path.join(configuredDir, "claude.sock") : null,
+        process.env.TMUX?.split(",")[0] ?? null,
+        process.env.TMPDIR ? path.join(process.env.TMPDIR, "claude-tmux-sockets", "claude.sock") : null,
+    ].filter((candidate) => Boolean(candidate));
+    return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+}
+function buildTmuxBaseArgs(socketPath) {
+    return socketPath ? ["-S", socketPath] : [];
+}
+function buildTmuxMonitorCommand(sessionName, socketPath) {
+    const socketArgs = socketPath ? `-S ${quoteShellValue(socketPath)} ` : "";
+    return `tmux ${socketArgs}attach -t ${quoteShellValue(sessionName)}`;
+}
+function getExtensionEntryPath() {
+    const currentPath = fileURLToPath(import.meta.url);
+    const extension = path.extname(currentPath) || ".js";
+    return path.join(path.dirname(currentPath), `index${extension}`);
+}
+function childStartupPrompt(parentAgentId) {
+    return [
+        `You are a Pinet subtree child supervised by ${parentAgentId}.`,
+        "Wait for the supervising worker's Pinet task, then do that task and report back through Pinet.",
+        "If you are not following Pinet yet, wait for the launcher to run /pinet follow.",
+    ].join(" ");
+}
+function buildLauncherScript(input) {
+    const inheritedEnvKeys = [
+        "PI_CODING_AGENT_DIR",
+        "PI_CODING_AGENT_SESSION_DIR",
+        "PI_OFFLINE",
+        "PI_SETTINGS_PATH",
+        "PINET_MESH_SECRET",
+        "PINET_MESH_SECRET_PATH",
+        "SLACK_APP_TOKEN",
+        "SLACK_BOT_TOKEN",
+    ];
+    const inheritedExports = inheritedEnvKeys
+        .map((key) => {
+        const value = process.env[key];
+        return value ? `export ${key}=${quoteShellValue(value)}` : null;
+    })
+        .filter((line) => Boolean(line));
+    const envExports = Object.entries(input.env).map(([key, value]) => `export ${key}=${quoteShellValue(value)}`);
+    const nickname = `Subtree ${input.env.PINET_SUBTREE_ROLE ?? "Worker"} ${input.env.PINET_LAUNCH_ID ?? randomSuffix()}`;
+    return [
+        "#!/bin/bash",
+        "set -euo pipefail",
+        `cd ${quoteShellValue(input.repoPath)}`,
+        ...inheritedExports,
+        ...envExports,
+        `export PI_NICKNAME=${quoteShellValue(nickname)}`,
+        `exec pi -e ${quoteShellValue(input.extensionEntryPath)} ${quoteShellValue(input.startupPrompt)}`,
+        "",
+    ].join("\n");
+}
+function isSubtreeChildAgent(agent, selfAgentId) {
+    return agent.id !== selfAgentId && agent.parentAgentId === selfAgentId;
+}
+function toSubtreeAgentRecord(db, agent) {
+    return {
+        emoji: agent.emoji,
+        name: agent.name,
+        id: agent.id,
+        pid: agent.pid,
+        status: agent.status,
+        metadata: agent.metadata,
+        lastHeartbeat: agent.lastHeartbeat,
+        lastSeen: agent.lastSeen,
+        disconnectedAt: agent.disconnectedAt,
+        resumableUntil: agent.resumableUntil,
+        outboundCount: agent.outboundCount,
+        pendingInboxCount: db.getPendingInboxCount(agent.id),
+        parentAgentId: agent.parentAgentId,
+        rootAgentId: agent.rootAgentId,
+        treeDepth: agent.treeDepth,
+        supervisionState: agent.supervisionState,
+        subtreeRole: agent.subtreeRole,
+        laneId: agent.laneId,
+    };
+}
+export function createSubtreeBrokerRuntime(deps) {
+    let activeBroker = null;
+    let selfAgentId = null;
+    let startedAt = null;
+    let activePaths = null;
+    let heartbeatTimer = null;
+    const spawnedWorkers = new Map();
+    function stopHeartbeat() {
+        if (!heartbeatTimer)
+            return;
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+    }
+    function startHeartbeat(broker, agentId) {
+        stopHeartbeat();
+        heartbeatTimer = setInterval(() => {
+            try {
+                broker.db.heartbeatAgent(agentId);
+            }
+            catch {
+                // Best effort only; normal broker maintenance will notice if this fails persistently.
+            }
+        }, HEARTBEAT_INTERVAL_MS);
+        heartbeatTimer.unref?.();
+    }
+    function currentChildren() {
+        const broker = activeBroker;
+        const agentId = selfAgentId;
+        if (!broker || !agentId)
+            return [];
+        return broker.db.getAllAgents().filter((agent) => isSubtreeChildAgent(agent, agentId));
+    }
+    function getStatus() {
+        const childLaunchEnv = activePaths && selfAgentId ? buildChildLaunchEnv(activePaths, selfAgentId) : {};
+        return {
+            active: activeBroker !== null,
+            selfAgentId,
+            startedAt,
+            paths: activePaths,
+            childLaunchEnv,
+            childLaunchHint: activePaths && selfAgentId
+                ? buildChildLaunchHint(activePaths, selfAgentId, deps.cwd)
+                : null,
+            childCount: currentChildren().length,
+            spawnedWorkers: [...spawnedWorkers.values()],
+        };
+    }
+    function drainSelfInbox(ctx, broker, agentId) {
+        const entries = broker.db.getInbox(agentId).map(toFollowerInboxEntry);
+        if (entries.length === 0)
+            return;
+        const synced = syncBrokerInboxEntries(entries);
+        const handledControlInboxIds = new Set();
+        for (const entry of synced.controlEntries) {
+            try {
+                const queued = deps.requestRemoteControl(entry.command, ctx);
+                if (queued.ackDisposition === "immediate") {
+                    handledControlInboxIds.add(entry.inboxId);
+                }
+                if (queued.shouldStartNow) {
+                    deps.runRemoteControl(entry.command, ctx);
+                }
+            }
+            catch (error) {
+                ctx.ui.notify(`Subtree Pinet control failed: ${deps.formatError(error)}`, "error");
+            }
+        }
+        if (handledControlInboxIds.size > 0) {
+            broker.db.markDelivered([...handledControlInboxIds], agentId);
+        }
+        if (synced.inboxMessages.length === 0)
+            return;
+        deps.pushInboxMessages(synced.inboxMessages);
+        deps.updateBadge();
+        deps.maybeDrainInboxIfIdle(ctx);
+    }
+    function readInbox(options = {}) {
+        if (!activeBroker || !selfAgentId)
+            return null;
+        if (options.threadId && !activeBroker.db.getThread(options.threadId))
+            return null;
+        const result = activeBroker.db.readInbox(selfAgentId, options);
+        return {
+            messages: result.messages.map((item) => ({
+                inboxId: item.entry.id,
+                delivered: item.entry.delivered,
+                readAt: item.entry.readAt,
+                message: item.message,
+            })),
+            unreadCountBefore: result.unreadCountBefore,
+            unreadCountAfter: result.unreadCountAfter,
+            unreadThreads: result.unreadThreads,
+            markedReadIds: result.markedReadIds,
+        };
+    }
+    async function sendMessage(target, body, metadata) {
+        if (!activeBroker || !selfAgentId)
+            return null;
+        const targetAgent = resolveDirectAgentTarget(activeBroker.db.getAgents(), target);
+        if (!targetAgent || targetAgent.id === selfAgentId)
+            return null;
+        const control = normalizeOutgoingPinetControlMessage(body, metadata);
+        const finalBody = control?.body ?? body;
+        const finalMetadata = control?.metadata ?? metadata;
+        const identity = deps.getAgentIdentity();
+        const result = dispatchDirectAgentMessage(activeBroker.db, {
+            senderAgentId: selfAgentId,
+            senderAgentName: identity.name || "Subtree Broker",
+            target,
+            body: finalBody,
+            ...(finalMetadata ? { metadata: finalMetadata } : {}),
+        });
+        return {
+            messageId: result.messageId,
+            target: result.target.name,
+            threadId: result.threadId,
+        };
+    }
+    function listAgents(includeGhosts = false) {
+        const broker = activeBroker;
+        if (!broker)
+            return null;
+        const agents = broker.db.getAllAgents();
+        const filtered = includeGhosts ? agents : agents.filter((agent) => !agent.disconnectedAt);
+        return filtered.map((agent) => toSubtreeAgentRecord(broker.db, agent));
+    }
+    async function sendFollowCommand(sessionName, tmuxBaseArgs) {
+        await execFileAsync("tmux", [
+            ...tmuxBaseArgs,
+            "send-keys",
+            "-t",
+            sessionName,
+            "-l",
+            "--",
+            "/pinet follow",
+        ]);
+        await execFileAsync("tmux", [...tmuxBaseArgs, "send-keys", "-t", sessionName, "Enter"]);
+    }
+    async function waitForSpawnedAgent(input) {
+        const deadline = Date.now() + input.timeoutMs;
+        let lastFollowAttemptAt = 0;
+        while (Date.now() < deadline) {
+            const agent = input.broker.db
+                .getAllAgents()
+                .find((candidate) => metadataString(candidate.metadata, "launchId") === input.launchId);
+            if (agent)
+                return agent;
+            if (Date.now() - lastFollowAttemptAt > 6_000) {
+                lastFollowAttemptAt = Date.now();
+                await sendFollowCommand(input.sessionName, input.tmuxBaseArgs).catch(() => {
+                    // The session may still be starting; the loop retries until timeout.
+                });
+            }
+            await delay(1_000);
+        }
+        throw new Error(`subtree worker session ${input.sessionName} started but did not register within ${input.timeoutMs}ms`);
+    }
+    async function requestChildExit(agent) {
+        await sendMessage(agent.id, "/exit", { subtreeLifecycle: "stop" }).catch(() => null);
+    }
+    async function killTmuxSession(sessionName, tmuxBaseArgs) {
+        await execFileAsync("tmux", [...tmuxBaseArgs, "has-session", "-t", sessionName]).catch(() => {
+            throw new Error("missing");
+        });
+        await execFileAsync("tmux", [...tmuxBaseArgs, "kill-session", "-t", sessionName]);
+    }
+    function childTmuxSessions(broker, agentId) {
+        const sessions = new Set();
+        for (const worker of spawnedWorkers.values()) {
+            sessions.add(worker.sessionName);
+        }
+        for (const agent of broker.db.getAllAgents()) {
+            if (!isSubtreeChildAgent(agent, agentId))
+                continue;
+            const session = metadataString(agent.metadata, "tmuxSession");
+            if (session)
+                sessions.add(session);
+        }
+        return [...sessions];
+    }
+    async function stopChildren(broker, agentId) {
+        const children = broker.db
+            .getAllAgents()
+            .filter((agent) => isSubtreeChildAgent(agent, agentId));
+        await Promise.all(children.map(requestChildExit));
+        if (children.length > 0) {
+            await delay(SUBTREE_CHILD_EXIT_GRACE_MS);
+        }
+        const tmuxSocketPath = findTmuxSocketPath();
+        const tmuxBaseArgs = buildTmuxBaseArgs(tmuxSocketPath);
+        await Promise.all(childTmuxSessions(broker, agentId).map((sessionName) => killTmuxSession(sessionName, tmuxBaseArgs).catch(() => undefined)));
+    }
+    async function stop(options = {}) {
+        stopHeartbeat();
+        const broker = activeBroker;
+        const agentId = selfAgentId;
+        if (!broker)
+            return;
+        try {
+            if (agentId && options.stopChildren !== false) {
+                await stopChildren(broker, agentId);
+            }
+            if (options.releaseIdentity && agentId) {
+                broker.db.unregisterAgent(agentId);
+            }
+            await broker.stop();
+        }
+        catch {
+            // Best effort; callers should be able to continue even if shutdown cleanup is partial.
+        }
+        finally {
+            activeBroker = null;
+            selfAgentId = null;
+            startedAt = null;
+            activePaths = null;
+            spawnedWorkers.clear();
+        }
+    }
+    async function start(ctx) {
+        if (activeBroker)
+            return getStatus();
+        const stableId = deps.getCentralAgentId() ?? deps.getAgentStableId();
+        const paths = buildSubtreeBrokerPaths(stableId);
+        fs.mkdirSync(paths.rootDir, { recursive: true });
+        const meshAuth = resolvePinetMeshAuth(deps.getSettings());
+        const broker = await startBroker({
+            dbPath: paths.dbPath,
+            socketPath: paths.socketPath,
+            lockPath: paths.lockPath,
+            ...(meshAuth.meshSecret ? { meshSecret: meshAuth.meshSecret } : {}),
+            ...(meshAuth.meshSecretPath ? { meshSecretPath: meshAuth.meshSecretPath } : {}),
+        });
+        const selfId = buildSelfAgentId(stableId);
+        const { name, emoji } = deps.getAgentIdentity();
+        const metadata = {
+            ...(await deps.getAgentMetadata("broker")),
+            subtreeBroker: true,
+            upstreamAgentId: deps.getCentralAgentId(),
+            subtreeSocketPath: paths.socketPath,
+        };
+        const selfAgent = broker.db.registerAgent(selfId, name ? `Subtree Broker ${name}` : "Subtree Broker", emoji || "🌳", process.pid, metadata, `${stableId}:subtree-broker`);
+        broker.server.setAgentRegistrationResolver((registration) => {
+            const role = deps.getMeshRoleFromMetadata(registration.metadata, "worker");
+            const identity = generateAgentName(registration.stableId ?? registration.agentId, role);
+            return {
+                name: registration.name || identity.name,
+                emoji: registration.emoji || identity.emoji,
+                metadata: {
+                    ...(registration.metadata ?? {}),
+                    subtreeBrokerAgentId: selfAgent.id,
+                    subtreeRootAgentId: selfAgent.id,
+                },
+            };
+        });
+        broker.server.onAgentMessage((targetAgentId) => {
+            if (targetAgentId !== selfAgent.id)
+                return;
+            drainSelfInbox(ctx, broker, selfAgent.id);
+        });
+        activeBroker = broker;
+        selfAgentId = selfAgent.id;
+        startedAt = new Date().toISOString();
+        activePaths = paths;
+        startHeartbeat(broker, selfAgent.id);
+        broker.db.setSetting("pinet.subtreeBrokerParentStableId", deps.getAgentStableId());
+        broker.db.setSetting("pinet.subtreeBrokerOwnerToken", buildPinetOwnerToken(stableId));
+        return getStatus();
+    }
+    async function spawnWorker(ctx, input) {
+        if (!input.task.trim())
+            throw new Error("spawn requires task");
+        if (!input.repo.trim())
+            throw new Error("spawn requires repo");
+        if (!activeBroker) {
+            await start(ctx);
+        }
+        if (!activeBroker || !activePaths || !selfAgentId) {
+            throw new Error("Subtree broker is not running.");
+        }
+        const repoPath = resolveRepoPath(input.repo, deps.cwd);
+        const role = normalizeRole(input.role);
+        const launchId = `subtree-${Date.now().toString(36)}-${randomSuffix()}`;
+        const sessionName = buildTmuxSessionName(repoPath, role, launchId);
+        const tmuxSocketPath = findTmuxSocketPath();
+        const tmuxBaseArgs = buildTmuxBaseArgs(tmuxSocketPath);
+        const monitorCommand = buildTmuxMonitorCommand(sessionName, tmuxSocketPath);
+        const childLaunchEnv = buildChildLaunchEnv(activePaths, selfAgentId, {
+            launchId,
+            role,
+            ...(input.laneId ? { laneId: input.laneId } : {}),
+            tmuxSession: sessionName,
+        });
+        const launchersDir = path.join(activePaths.rootDir, "launchers");
+        fs.mkdirSync(launchersDir, { recursive: true });
+        const launcherPath = path.join(launchersDir, `${sessionName}.sh`);
+        fs.writeFileSync(launcherPath, buildLauncherScript({
+            repoPath,
+            env: childLaunchEnv,
+            extensionEntryPath: getExtensionEntryPath(),
+            startupPrompt: childStartupPrompt(selfAgentId),
+        }), { mode: 0o700 });
+        await execFileAsync("tmux", [
+            ...tmuxBaseArgs,
+            "new-session",
+            "-d",
+            "-s",
+            sessionName,
+            launcherPath,
+        ]);
+        const workerRecord = {
+            launchId,
+            sessionName,
+            repoPath,
+            role,
+            laneId: input.laneId ?? null,
+            agentId: null,
+            startedAt: new Date().toISOString(),
+            monitorCommand,
+        };
+        spawnedWorkers.set(launchId, workerRecord);
+        const agent = await waitForSpawnedAgent({
+            broker: activeBroker,
+            launchId,
+            sessionName,
+            tmuxBaseArgs,
+            timeoutMs: input.waitForRegistrationMs ?? DEFAULT_SPAWN_REGISTRATION_TIMEOUT_MS,
+        });
+        const updatedRecord = { ...workerRecord, agentId: agent.id };
+        spawnedWorkers.set(launchId, updatedRecord);
+        const messageResult = await sendMessage(agent.id, input.task, {
+            subtreeTask: true,
+            launchId,
+            role,
+            ...(input.laneId ? { laneId: input.laneId } : {}),
+        });
+        if (!messageResult) {
+            throw new Error(`subtree worker ${agent.id} registered but could not receive the task`);
+        }
+        return {
+            status: "started",
+            launchId,
+            sessionName,
+            repoPath,
+            role,
+            laneId: input.laneId ?? null,
+            agentId: agent.id,
+            agentName: agent.name,
+            messageId: messageResult.messageId,
+            threadId: messageResult.threadId,
+            monitorCommand,
+            socketPath: activePaths.socketPath,
+            dbPath: activePaths.dbPath,
+            childLaunchEnv,
+        };
+    }
+    return {
+        start,
+        stop,
+        getStatus,
+        readInbox,
+        sendMessage,
+        listAgents,
+        spawnWorker,
+        isActive: () => activeBroker !== null,
+    };
+}

package/manifest.yaml

@@ -11,6 +11,14 @@ features:
   bot_user:
     display_name: Pinet
     always_online: true
+  # Default packaged command for the Pinet app. For Oathgate or another app name,
+  # either edit this command before manual Slack import or run `pnpm deploy:slack`
+  # with slackCommandName/slackCommandNames configured so deployment rewrites it.
+  slash_commands:
+    - command: /pinet
+      description: Show the Pinet broker roster and current work
+      usage_hint: "agents list [all]"
+      should_escape: false
   assistant_view:
     assistant_description: Pi coding agent
     suggested_prompts: []
@@ -23,6 +31,7 @@ oauth_config:
       - channels:history
       - channels:read
       - chat:write
+      - commands
       - files:read
       - files:write
       - bookmarks:read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinet/slack-bridge",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Pi package for Pinet Slack assistant integration — multi-agent broker, thread routing, and inbox tools",
   "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
@@ -49,17 +49,19 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@pinet/broker-core": "0.1.2",
-    "@pinet/imessage-bridge": "0.1.2",
-    "@pinet/pinet-core": "0.1.2",
-    "@pinet/transport-core": "0.1.2",
+    "@pinet/broker-core": "0.2.0",
+    "@pinet/imessage-bridge": "0.2.0",
+    "@pinet/pinet-core": "0.2.0",
+    "@pinet/transport-core": "0.2.0",
     "@sinclair/typebox": "^0.34.49"
   },
   "types": "./dist/index.d.ts",
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0"
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-tui": "^0.74.0"
   }
 }

package/skills/slack-bridge/SKILL.md

@@ -50,7 +50,7 @@ should use the colon form.
 
 - Thread/channel messaging: `post_channel`, `read`, `read_channel`, `export`
 - Lightweight acknowledgement: `react`
-- Files/snippets: `upload`
+- Files/snippets: `upload`, `file`; `slack_send.files` and `post_channel.files` for text plus attachments in one message
 - Time-based follow-up: `schedule`
 - People/timing: `presence`
 - Durable channel affordances: `pin`, `bookmark`
@@ -144,6 +144,65 @@ snippets:
 ]
 ````
 
+## File workflows
+
+For outbound local files, attach them to the message-posting surface you are
+already using. Use `slack_send.files` for owned assistant-thread replies, and
+`slack` action `post_channel` with `args.files` for explicit channel/thread
+posts. Both use the same file object shape and send text plus files in one Slack
+message:
+
+```json
+{
+  "text": "Here is the report and the raw capture.",
+  "thread_ts": "1712345678.000100",
+  "files": [
+    { "path": "./out/report.pdf", "title": "Report" },
+    { "path": "/tmp/capture.bin", "filename": "capture.bin" }
+  ]
+}
+```
+
+```json
+{
+  "action": "post_channel",
+  "args": {
+    "channel": "#deployments",
+    "text": "Here is the deploy evidence.",
+    "files": [{ "path": "/tmp/evidence.png", "filename": "evidence.png" }]
+  }
+}
+```
+
+Local path guardrails still apply: paths must resolve inside the current working
+directory or the system temp directory. Binary files are supported.
+
+For inbound Slack-hosted files, `slack` action `read` downloads attached files to
+the local temp cache by default and returns safe descriptors alongside the
+message metadata. Use `args.download_files=false` when you only need message text
+and file metadata.
+
+Use the explicit `file` action when you have a specific file ID to retry,
+validate, or fetch outside a normal read flow:
+
+```json
+{
+  "action": "file",
+  "args": {
+    "op": "download",
+    "file_id": "F0123456789",
+    "thread_ts": "1712345678.000100",
+    "message_ts": "1712345678.000200"
+  }
+}
+```
+
+Both read-time downloads and the explicit file action download Slack-hosted user
+content into the local temp cache and return safe descriptors: file ID,
+filename/type, local temp path, size, SHA-256, cache directory, expiry, and
+residual risk notes. They must not print private Slack download URLs or raw file
+contents.
+
 ## Modal patterns
 
 Modal actions require a fresh Slack `trigger_id` from a recent interaction. The