@pinet/slack-bridge 0.1.0

package/dist/tool-registration-runtime.d.ts

@@ -0,0 +1,13 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type RegisterIMessageToolsDeps } from "./imessage-tools.js";
+import { type RegisterPinetToolsDeps } from "./pinet-tools.js";
+import { type RegisterSlackToolsDeps } from "./slack-tools.js";
+export interface ToolRegistrationRuntimeDeps {
+    slackTools: RegisterSlackToolsDeps;
+    pinetTools: RegisterPinetToolsDeps;
+    iMessageTools: RegisterIMessageToolsDeps;
+}
+export interface ToolRegistrationRuntime {
+    register: (pi: ExtensionAPI) => void;
+}
+export declare function createToolRegistrationRuntime(deps: ToolRegistrationRuntimeDeps): ToolRegistrationRuntime;

package/dist/tool-registration-runtime.js

@@ -0,0 +1,13 @@
+import { registerIMessageTools } from "./imessage-tools.js";
+import { registerPinetTools } from "./pinet-tools.js";
+import { registerSlackTools } from "./slack-tools.js";
+export function createToolRegistrationRuntime(deps) {
+    function register(pi) {
+        registerSlackTools(pi, deps.slackTools);
+        registerPinetTools(pi, deps.pinetTools);
+        registerIMessageTools(pi, deps.iMessageTools);
+    }
+    return {
+        register,
+    };
+}

package/dist/ttl-cache.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Lightweight TTL + max-size cache.
+ *
+ * Entries expire after `ttlMs` milliseconds and are lazily evicted on
+ * access.  When the cache exceeds `maxSize`, the oldest entry (by
+ * insertion / last-update order) is dropped — Map iteration order
+ * guarantees FIFO.
+ */
+export declare class TtlCache<K, V> {
+    private readonly map;
+    private readonly maxSize;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(options: {
+        maxSize: number;
+        ttlMs: number;
+        now?: () => number;
+    });
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    get size(): number;
+    /** Iterate live (non-expired) entries. */
+    entries(): IterableIterator<[K, V]>;
+    /** Sweep all expired entries in one pass. */
+    sweep(): number;
+    clear(): void;
+    private evictOverflow;
+}
+/**
+ * TTL + max-size Set — thin wrapper around TtlCache<V, true>.
+ */
+export declare class TtlSet<V> {
+    private readonly cache;
+    constructor(options: {
+        maxSize: number;
+        ttlMs: number;
+        now?: () => number;
+    });
+    add(value: V): this;
+    has(value: V): boolean;
+    delete(value: V): boolean;
+    get size(): number;
+    sweep(): number;
+    clear(): void;
+}

package/dist/ttl-cache.js

@@ -0,0 +1,105 @@
+/**
+ * Lightweight TTL + max-size cache.
+ *
+ * Entries expire after `ttlMs` milliseconds and are lazily evicted on
+ * access.  When the cache exceeds `maxSize`, the oldest entry (by
+ * insertion / last-update order) is dropped — Map iteration order
+ * guarantees FIFO.
+ */
+export class TtlCache {
+    map = new Map();
+    maxSize;
+    ttlMs;
+    now;
+    constructor(options) {
+        this.maxSize = options.maxSize;
+        this.ttlMs = options.ttlMs;
+        this.now = options.now ?? (() => Date.now());
+    }
+    get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        if (this.now() - entry.touchedAt > this.ttlMs) {
+            this.map.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        // Delete first so re-insertion moves the key to the end (Map ordering).
+        this.map.delete(key);
+        this.map.set(key, { value, touchedAt: this.now() });
+        this.evictOverflow();
+        return this;
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    delete(key) {
+        return this.map.delete(key);
+    }
+    get size() {
+        return this.map.size;
+    }
+    /** Iterate live (non-expired) entries. */
+    *entries() {
+        const now = this.now();
+        for (const [key, entry] of this.map) {
+            if (now - entry.touchedAt <= this.ttlMs) {
+                yield [key, entry.value];
+            }
+        }
+    }
+    /** Sweep all expired entries in one pass. */
+    sweep() {
+        const now = this.now();
+        let swept = 0;
+        for (const [key, entry] of this.map) {
+            if (now - entry.touchedAt > this.ttlMs) {
+                this.map.delete(key);
+                swept++;
+            }
+        }
+        return swept;
+    }
+    clear() {
+        this.map.clear();
+    }
+    evictOverflow() {
+        while (this.map.size > this.maxSize) {
+            const oldest = this.map.keys().next();
+            if (oldest.done)
+                break;
+            this.map.delete(oldest.value);
+        }
+    }
+}
+/**
+ * TTL + max-size Set — thin wrapper around TtlCache<V, true>.
+ */
+export class TtlSet {
+    cache;
+    constructor(options) {
+        this.cache = new TtlCache(options);
+    }
+    add(value) {
+        this.cache.set(value, true);
+        return this;
+    }
+    has(value) {
+        return this.cache.has(value);
+    }
+    delete(value) {
+        return this.cache.delete(value);
+    }
+    get size() {
+        return this.cache.size;
+    }
+    sweep() {
+        return this.cache.sweep();
+    }
+    clear() {
+        this.cache.clear();
+    }
+}

package/manifest.yaml

@@ -0,0 +1,57 @@
+display_information:
+  name: Pinet
+  description: Hi, im Pinet (pronounce pie-net like apple-pie and basketball net)
+  background_color: "#87390c"
+  long_description: "I am a friendly one and I can wear many hats at once, ask me anything! In my free time I like to take long walks in the park and bring a picnic. My favorite food is pie of course :cake:"
+features:
+  app_home:
+    home_tab_enabled: true
+    messages_tab_enabled: true
+    messages_tab_read_only_enabled: false
+  bot_user:
+    display_name: Pinet
+    always_online: true
+  assistant_view:
+    assistant_description: Pi coding agent
+    suggested_prompts: []
+oauth_config:
+  scopes:
+    bot:
+      - reactions:write
+      - app_mentions:read
+      - assistant:write
+      - channels:history
+      - channels:read
+      - chat:write
+      - files:read
+      - files:write
+      - bookmarks:read
+      - bookmarks:write
+      - groups:history
+      - groups:read
+      - im:history
+      - im:read
+      - im:write
+      - users:read
+      - reactions:read
+      - canvases:read
+      - canvases:write
+      - pins:read
+      - pins:write
+  pkce_enabled: false
+settings:
+  event_subscriptions:
+    bot_events:
+      - app_mention
+      - app_home_opened
+      - assistant_thread_started
+      - assistant_thread_context_changed
+      - reaction_added
+      - message.channels
+      - message.groups
+      - message.im
+  interactivity:
+    is_enabled: true
+  org_deploy_enabled: false
+  socket_mode_enabled: true
+  token_rotation_enabled: false

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@pinet/slack-bridge",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Slack assistant integration for pi (Pinet) — multi-agent broker, thread routing, and inbox tools",
+  "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gugu91/extensions.git",
+    "directory": "slack-bridge"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "manifest.yaml",
+    "skills/",
+    "dist/"
+  ],
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "build": "node ../scripts/build-package.mjs",
+    "prepack": "pnpm run build",
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@pinet/broker-core": "0.1.0",
+    "@pinet/imessage-bridge": "0.1.0",
+    "@pinet/pinet-core": "0.1.0",
+    "@pinet/transport-core": "0.1.0",
+    "@sinclair/typebox": "^0.34.49"
+  },
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0"
+  }
+}

package/skills/pinet-skin-creator/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: pinet-skin-creator
+description: Guides safe creation and editing of Pinet skin descriptors, curated character/name pools, persona snippets, emoji/style, and status vocabulary. Use when designing or refining non-default Pinet skins or reviewing skin descriptor changes.
+---
+
+# Pinet Skin Creator
+
+Use this skill when asked to create, edit, or review Pinet skin descriptors or
+curated Pinet character sets. It is intentionally a **design/build workflow**:
+do not add model calls to broker startup or follower join paths.
+
+## Core design rules
+
+- **Default/classic stays random.** Preserve the existing whimsical random
+  adjective/color/animal identity generation for the default/classic skin.
+- **Curated skins are JSON descriptors.** Non-default skins should ship external
+  JSON descriptor assets with curated/prebaked identity pools, 1–3 word authored
+  display names, static emoji, personae, emoji/style guidance, and status
+  vocabulary.
+- **No LLM in startup/join.** Broker startup and follower join must remain
+  deterministic, fast, offline-tolerant, and usable without model availability.
+- **Persist concrete assignments.** If a future `auto` mode chooses a skin or
+  character after runtime is live, persist the resolved concrete assignment and
+  keep a deterministic fallback.
+- **Presentation only.** Skins may shape names, emoji, tone, persona snippets,
+  and status display vocabulary. They must not change tool permissions,
+  broker/follower roles, task ownership, guardrails, or routing authority.
+
+## Workflow
+
+1. **Clarify the target**
+   - Skin key and aliases.
+   - Intended theme, tone, and setting.
+   - Supported roles: broker, worker/follower, reviewer, PM/coordinator, or
+     future role labels.
+   - Whether the task is creating a new skin or editing an existing one.
+
+2. **Draft the descriptor**
+   - Start from `templates/pinet-skin-descriptor.json`.
+   - Follow `references/descriptor-format.md` for fields and constraints.
+   - Prefer rich curated/prebaked identity lists over random display-name
+     combinators, tiny hardcoded TypeScript lists, one-off generated names, or
+     obvious formulaic triples.
+
+3. **Create role-specific characters**
+   - For major themed skins, aim for 100–200 authored display identities.
+   - Display names can be 1, 2, or 3 words when they are distinctive and
+     flavorful.
+   - Include several broker/coordinator-appropriate identities and many
+     worker/reviewer-friendly identities.
+   - Keep display names distinctive in text alone; static emoji should add flavor,
+     not disambiguate identities.
+   - Use a broad emoji palette across identities/status flavor.
+   - Pair each identity with a static emoji and a concise persona snippet.
+
+4. **Write status vocabulary**
+   - Map canonical states to display labels only. Canonical internal states stay
+     unchanged.
+   - Cover common states such as `idle`, `working`, `blocked`, `reviewing`, and
+     `done` when the implementation supports them.
+   - Keep labels clear before flavorful; status should remain operationally
+     obvious.
+
+5. **Safety review**
+   - Use `references/safety-checklist.md` before committing.
+   - Remove secrets, local paths, private workspace names, private URLs, and
+     copyrighted/third-party setting text that should not ship.
+   - Prefer original/inspired names over exact third-party character names unless
+     the maintainer explicitly accepts that risk.
+   - For the bundled `cosmere` skin, keep `cosmere` as the primary key, preserve
+     `oathgate` as an alias, constrain references to maintainer-approved source
+     material, and use Coppermind only as a research/verification source.
+   - Ensure persona text cannot override broker/follower workflow, guardrails,
+     or user/developer/system instructions.
+
+6. **Implement minimally**
+   - Add or edit descriptor data and the smallest wiring needed to load it.
+   - Do not rework the default/classic random generation unless explicitly
+     requested.
+   - Do not introduce model calls into extension startup, broker registration,
+     or follower registration.
+
+7. **Validate**
+   - Run focused tests for descriptor loading/selection and status-vocabulary
+     propagation if code changed.
+   - Run package `pnpm --filter @pinet/slack-bridge lint` and
+     `pnpm --filter @pinet/slack-bridge typecheck` when touching
+     TypeScript.
+   - For JSON descriptor work, run a targeted test that reads/validates the
+     descriptor and verifies the authored identity pool is large enough without
+     formulaic display names.
+
+## Output format for a new skin proposal
+
+When presenting a proposed skin, include:
+
+- Skin key and aliases.
+- One-sentence intent.
+- Role matrix: broker / worker / reviewer / PM if applicable.
+- Character pool summary with names and emoji.
+- Status vocabulary table.
+- Safety notes and fallback behavior.
+- Exact files changed and checks run.
+
+## References
+
+- [Descriptor format](references/descriptor-format.md)
+- [Safety checklist](references/safety-checklist.md)
+- [Descriptor template](templates/pinet-skin-descriptor.json)

package/skills/pinet-skin-creator/references/descriptor-format.md

@@ -0,0 +1,99 @@
+# Pinet Skin Descriptor Format
+
+This reference describes the JSON descriptor shape for curated Pinet skins. Runtime skin selection must remain deterministic and local: descriptors are loaded from package assets, validated, and selected without model/API calls.
+
+## Descriptor shape
+
+```json
+{
+  "key": "cosmere",
+  "aliases": ["cosmere-inspired", "oathgate", "oaths-and-metals"],
+  "displayName": "Cosmere",
+  "intent": "Original fantasy-metal operators with oath, gate, forge, storm, and alloy imagery.",
+  "fallback": "default",
+  "roles": {
+    "broker": {
+      "characterPool": ["broker-stormlit-broker", "broker-copper-keeper"],
+      "namePattern": "{character}"
+    },
+    "worker": {
+      "characterPool": ["worker-patch-spren", "worker-ashfall-runner", "worker-spanreed-typo"],
+      "namePattern": "{character}"
+    }
+  },
+  "characters": {
+    "broker-stormlit-broker": {
+      "name": "Stormlit Broker",
+      "emoji": "⛈️",
+      "persona": "Highstorm-ready coordinator; keeps pressure visible and lanes safe.",
+      "style": ["measured", "protective", "clear"]
+    },
+    "worker-patch-spren": {
+      "name": "Patch Spren",
+      "emoji": "🩹",
+      "persona": "Practical worker; ships small durable changes and reports checks.",
+      "style": ["practical", "concise", "status-first"]
+    }
+  },
+  "statusVocabulary": {
+    "idle": "holding oath",
+    "working": "at the forge",
+    "healthy": "signal bright",
+    "stale": "storm-dimmed",
+    "ghost": "beyond the gate",
+    "resumable": "oath recoverable"
+  }
+}
+```
+
+## Required semantics
+
+- `key`: stable lowercase identifier. Runtime built-ins currently accept the configured built-in keys.
+- `aliases`: alternate user-facing names. Keep backward-compatible aliases when renaming skins.
+- `displayName`: short human-readable name.
+- `intent`: one sentence describing the operational feel.
+- `fallback`: deterministic fallback skin, normally `default`.
+- `roles`: maps Pinet roles to selection pools. `broker` and `worker` are required for runtime built-ins.
+- `roles.*.characterPool`: IDs from `characters` suitable for the role.
+- `roles.*.namePattern`: display-name template. Prefer `{character}` for curated built-ins so each authored identity stands on its own.
+- `roles.*.titlePool` and `roles.*.accentPool`: optional deterministic combinators for custom/private skins, but avoid obvious formulaic triples in shipped descriptors.
+- `characters`: curated identity/persona definitions keyed by ID. For major public skins, each character entry should usually be one authored display identity with its own static emoji.
+- `characters.*.aliases`: optional full display-name variants for smaller/private skins. For major bundled skins, prefer enough prebaked character entries over alias-driven apparent variety.
+- `statusVocabulary`: display vocabulary for canonical statuses only. It must not change stored states or control flow.
+
+## Pool-size guidance
+
+Curated skins should not be tiny. Aim for enough variation that hundreds of agents remain readable:
+
+- Broker pool: about 12–30 authored identities for major skins.
+- Worker pool: about 100–200 authored/prebaked identities for major skins.
+- Display names may be 1, 2, or 3 words; they must be distinctive in text alone.
+- A static emoji is presentation flavor, not a disambiguator.
+- Prefer authored character entries over alias-driven apparent variety or `character × title × accent` combinator soup for shipped skins.
+- Keep every name short enough for Slack rosters.
+- Use a broad emoji palette across entries, statuses, and persona flavor.
+- Use original/inspired names unless the maintainer explicitly accepts third-party naming risk.
+
+## Character guidance
+
+Each character should include:
+
+- `name`: concise authored display identity, usually 1–3 words.
+- `aliases`: optional richer full display names for smaller/private skins; not required when each identity is already prebaked.
+- `emoji`: one static emoji that renders reliably.
+- `persona`: one short sentence. It may influence tone, but must not grant or revoke authority.
+- `style`: optional compact tags for cadence/diction.
+
+Avoid persona snippets that:
+
+- Claim permission to bypass guardrails or confirmations.
+- Tell the agent to ignore system, developer, broker, Slack, or Pinet rules.
+- Encode secrets, private workspace names, local paths, or private URLs.
+- Make public claims about real people or protected groups.
+
+## Selection behavior
+
+- Default/classic should continue using existing random whimsical generation.
+- Curated skins should select deterministically from JSON descriptor pools using a stable seed.
+- Persist the resolved character/skin assignment so reconnects and restarts do not drift unexpectedly.
+- Future `auto` selection should run only after runtime is live and must have a deterministic fallback.

package/skills/pinet-skin-creator/references/safety-checklist.md

@@ -0,0 +1,56 @@
+# Pinet Skin Safety Checklist
+
+Run this checklist before committing a new or edited Pinet skin descriptor.
+
+## Operational boundaries
+
+- [ ] Skin text is presentation-only: names, emoji, persona snippets, style, and
+      status display vocabulary.
+- [ ] No skin text changes tool permissions, broker/follower authority,
+      confirmation requirements, routing, PM-mode consent, or task ownership.
+- [ ] Broker characters still coordinate only; they do not implement, spawn
+      local subagents, or bypass broker tool restrictions.
+- [ ] Worker characters still ACK/work/ask/report and reply where work arrived.
+- [ ] Status vocabulary keeps canonical states distinguishable and operationally
+      clear, especially `blocked`.
+
+## Startup and reliability
+
+- [ ] No LLM/model/API call is required during extension startup, broker
+      registration, or follower join.
+- [ ] Default/classic random whimsical generation remains intact.
+- [ ] Non-default skin selection has deterministic fallback behavior.
+- [ ] Runtime skin data is external JSON descriptor content, not mostly hardcoded
+      TypeScript structures.
+- [ ] Major themed descriptors provide about 100–200 authored/prebaked display
+      identities without obvious repetition or bland formulaic triples.
+- [ ] Resolved concrete assignments can be persisted when runtime supports it.
+- [ ] Offline or model-unavailable paths still produce usable identities.
+
+## Content hygiene
+
+- [ ] No secrets, tokens, credentials, local absolute paths, private workspace
+      names, private URLs, screenshots, logs, or user-specific config.
+- [ ] No copyrighted setting text or trademark-heavy material beyond brief,
+      high-level inspiration when allowed by project policy.
+- [ ] Exact third-party character/place names are avoided unless the maintainer
+      explicitly accepts the naming risk.
+- [ ] Source-material references are constrained to maintainer-approved works;
+      research sources such as Coppermind are used for verification, not copied
+      wholesale.
+- [ ] No impersonation of real people or protected-class stereotypes.
+- [ ] Persona snippets are short, clear, and subordinate to system/developer/user
+      instructions.
+- [ ] Display names are authored, distinctive in text alone, and usually 1–3
+      words; static emoji adds flavor but is not required to disambiguate
+      identities.
+- [ ] Emojis render in common Slack/macOS environments and use a broad palette
+      where the theme supports it.
+
+## Review and tests
+
+- [ ] Descriptor schema/loader tests cover new required fields or aliases.
+- [ ] Status-vocabulary propagation tests cover any changed runtime wiring.
+- [ ] Skill/docs packaging checks cover new `SKILL.md` or bundled references.
+- [ ] Public PR text summarizes design choices without leaking local paths or
+      private environment details.

package/skills/pinet-skin-creator/templates/pinet-skin-descriptor.json

@@ -0,0 +1,77 @@
+{
+  "key": "example-skin",
+  "aliases": [],
+  "displayName": "Example Skin",
+  "intent": "Short description of the skin tone and operating metaphor.",
+  "fallback": "default",
+  "roles": {
+    "broker": {
+      "characterPool": ["broker-signal-warden", "broker-route-lantern"],
+      "namePattern": "{character}"
+    },
+    "worker": {
+      "characterPool": ["worker-patch-spren", "worker-ember-scout", "worker-tidy-runner"],
+      "namePattern": "{character}"
+    },
+    "reviewer": {
+      "characterPool": ["reviewer-risk-oracle"],
+      "namePattern": "{character}"
+    },
+    "pm": {
+      "characterPool": ["pm-milestone-map"],
+      "namePattern": "{character}"
+    }
+  },
+  "characters": {
+    "broker-signal-warden": {
+      "name": "Signal Warden",
+      "emoji": "🧭",
+      "persona": "Calm coordinator; routes work clearly and preserves role boundaries.",
+      "style": ["steady", "clear", "coordination-first"]
+    },
+    "broker-route-lantern": {
+      "name": "Route Lantern",
+      "emoji": "🏮",
+      "persona": "Visible broker; keeps ownership, blockers, and escalation lit.",
+      "style": ["visible", "protective", "accountable"]
+    },
+    "worker-patch-spren": {
+      "name": "Patch Spren",
+      "emoji": "🩹",
+      "persona": "Practical worker; ships small durable changes and reports checks.",
+      "style": ["practical", "concise", "test-led"]
+    },
+    "worker-ember-scout": {
+      "name": "Ember Scout",
+      "emoji": "🔎",
+      "persona": "Curious scout; investigates uncertainty and returns grounded findings.",
+      "style": ["curious", "bounded", "evidence-led"]
+    },
+    "worker-tidy-runner": {
+      "name": "Tidy Runner",
+      "emoji": "🏃",
+      "persona": "Fast worker; keeps momentum without hiding blockers.",
+      "style": ["fast", "visible", "disciplined"]
+    },
+    "reviewer-risk-oracle": {
+      "name": "Risk Oracle",
+      "emoji": "🧐",
+      "persona": "Skeptical reviewer; checks correctness, safety, and maintainability.",
+      "style": ["skeptical", "precise", "fair"]
+    },
+    "pm-milestone-map": {
+      "name": "Milestone Map",
+      "emoji": "🗺️",
+      "persona": "Planning coordinator; breaks complex work into clear lanes and checkpoints.",
+      "style": ["structured", "calm", "scope-aware"]
+    }
+  },
+  "statusVocabulary": {
+    "idle": "standing by",
+    "working": "on the lane",
+    "healthy": "signal clear",
+    "stale": "signal dim",
+    "ghost": "off grid",
+    "resumable": "ready to resume"
+  }
+}