@openscout/protocol 0.2.102 → 0.2.104

package/dist/actors.d.ts

@@ -1,8 +1,8 @@
 import type { ActorKind, AdvertiseScope, AgentState, DeliveryTransport, MetadataMap, ScoutId } from "./common.js";
 export type AgentClass = "general" | "builder" | "reviewer" | "researcher" | "operator" | "bridge" | "system";
 export type AgentCapability = "chat" | "invoke" | "deliver" | "speak" | "listen" | "bridge" | "summarize" | "review" | "execute";
-export type AgentEndpointTransport = Extract<DeliveryTransport, "local_socket" | "http" | "websocket" | "pairing_bridge" | "claude_channel" | "claude_stream_json" | "codex_app_server" | "codex_exec" | "claude_resume" | "pi_rpc" | "grok_acp" | "kimi_acp" | "cursor_acp" | "opencode_acp" | "tmux" | "cursor_exec" | "cursor_cli_text" | "cursor_cli_stream_json" | "cursor_sdk_local">;
-export declare const AGENT_HARNESSES: readonly ["codex", "claude", "grok", "grok-acp", "kimi", "flue", "cursor", "opencode", "native", "worker", "bridge", "http", "pi"];
+export type AgentEndpointTransport = Extract<DeliveryTransport, "local_socket" | "http" | "websocket" | "pairing_bridge" | "claude_channel" | "claude_stream_json" | "codex_app_server" | "codex_exec" | "claude_resume" | "pi_rpc" | "grok_acp" | "kimi_acp" | "cursor_acp" | "opencode_acp" | "devin_acp" | "tmux" | "cursor_exec" | "cursor_cli_text" | "cursor_cli_stream_json" | "cursor_sdk_local">;
+export declare const AGENT_HARNESSES: readonly ["codex", "claude", "grok", "grok-acp", "kimi", "flue", "cursor", "opencode", "devin", "native", "worker", "bridge", "http", "pi"];
 export type AgentHarness = typeof AGENT_HARNESSES[number];
 export type WakePolicy = "manual" | "on_demand" | "keep_warm";
 export interface ActorIdentity {

package/dist/actors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actors.d.ts","sourceRoot":"","sources":["../src/actors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,OAAO,EACR,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,SAAS,GACT,UAAU,GACV,YAAY,GACZ,UAAU,GACV,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,QAAQ,GACR,SAAS,GACT,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAC1C,iBAAiB,EACf,cAAc,GACd,MAAM,GACN,WAAW,GACX,gBAAgB,GAChB,gBAAgB,GAChB,oBAAoB,GACpB,kBAAkB,GAClB,YAAY,GACZ,eAAe,GACf,QAAQ,GACR,UAAU,GACV,UAAU,GACV,YAAY,GACZ,cAAc,GACd,MAAM,GACN,aAAa,GACb,iBAAiB,GACjB,wBAAwB,GACxB,kBAAkB,CACrB,CAAC;AAEF,eAAO,MAAM,eAAe,oIAclB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;AAE1D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,cAAc,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,sBAAsB,CAAC;IAClC,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB"}
+{"version":3,"file":"actors.d.ts","sourceRoot":"","sources":["../src/actors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,OAAO,EACR,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,SAAS,GACT,UAAU,GACV,YAAY,GACZ,UAAU,GACV,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,QAAQ,GACR,SAAS,GACT,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAC1C,iBAAiB,EACf,cAAc,GACd,MAAM,GACN,WAAW,GACX,gBAAgB,GAChB,gBAAgB,GAChB,oBAAoB,GACpB,kBAAkB,GAClB,YAAY,GACZ,eAAe,GACf,QAAQ,GACR,UAAU,GACV,UAAU,GACV,YAAY,GACZ,cAAc,GACd,WAAW,GACX,MAAM,GACN,aAAa,GACb,iBAAiB,GACjB,wBAAwB,GACxB,kBAAkB,CACrB,CAAC;AAEF,eAAO,MAAM,eAAe,6IAelB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;AAE1D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,cAAc,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,sBAAsB,CAAC;IAClC,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB"}

package/dist/actors.js

@@ -7,6 +7,7 @@ export const AGENT_HARNESSES = [
     "flue",
     "cursor",
     "opencode",
+    "devin",
     "native",
     "worker",
     "bridge",

package/dist/broker-routes.d.ts

@@ -18,6 +18,7 @@ export declare const scoutBrokerPaths: {
         readonly messages: "/v1/messages";
         readonly brokerMessages: "/v1/broker/messages";
         readonly eventsStream: "/v1/events/stream";
+        readonly commands: "/v1/commands";
         readonly actors: "/v1/actors";
         readonly agents: "/v1/agents";
         readonly endpoints: "/v1/endpoints";

package/dist/broker-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-routes.d.ts","sourceRoot":"","sources":["../src/broker-routes.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCnB,CAAC;AAEX,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG3E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKvE;AAED,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjE"}
+{"version":3,"file":"broker-routes.d.ts","sourceRoot":"","sources":["../src/broker-routes.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CnB,CAAC;AAEX,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG3E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKvE;AAED,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/dist/broker-routes.js

@@ -24,6 +24,7 @@ export const scoutBrokerPaths = {
         messages: "/v1/messages",
         brokerMessages: "/v1/broker/messages",
         eventsStream: "/v1/events/stream",
+        commands: "/v1/commands",
         actors: "/v1/actors",
         agents: "/v1/agents",
         endpoints: "/v1/endpoints",

package/dist/channel-identity.d.ts

@@ -20,6 +20,83 @@ export declare function isOpaqueChannelId(value: string | null | undefined): val
 export declare function directChannelNaturalKey(participantIds: ScoutId[]): string;
 export declare function namedChannelNaturalKey(channel: string): string;
 export declare function systemChannelNaturalKey(name: string): string;
+/**
+ * The space every channel that predates spaces belongs to.
+ *
+ * It is not a migration target; it is the name of what already exists. A
+ * channel with no space marker *is* a default-space channel, decided at read
+ * time by {@link channelSpaceSlug}, so no record is ever rewritten to acquire
+ * one.
+ */
+export declare const DEFAULT_CHAT_SPACE_SLUG = "home";
+/** Metadata key carrying a channel's (or a space record's) space slug. */
+export declare const CHANNEL_SPACE_SLUG_METADATA = "spaceSlug";
+/** Natural-key prefix for the conversation record that *is* a space. */
+export declare const SPACE_NATURAL_KEY_PREFIX = "space:";
+export declare function isChatSpaceSlug(value: string | null | undefined): value is string;
+/**
+ * Read a slug from untrusted input, or return `null`.
+ *
+ * Lowercasing and trimming are accepted because they cannot change which space
+ * is meant. Anything else -- a space character, a slash, a percent escape --
+ * is refused rather than repaired: silently rewriting `work/secret` into
+ * `worksecret` would resolve a request to a space the caller did not name.
+ */
+export declare function normalizeChatSpaceSlug(value: string | null | undefined): string | null;
+/**
+ * Derive a slug from a human title, for creation only.
+ *
+ * This one *does* rewrite, because the title is prose the operator typed and
+ * the slug is an identifier we are minting from it. It is never used to
+ * interpret a slug that arrived on a request.
+ */
+export declare function chatSpaceSlugFromTitle(title: string): string | null;
+/** The natural key of the conversation record that carries a space. */
+export declare function spaceNaturalKey(spaceSlug: string): string;
+/**
+ * The natural key of a named channel *inside a space*.
+ *
+ * The default space returns the byte-identical legacy string, which is what
+ * keeps every channel that exists today on the exact id it already has:
+ * `stableChannelId` is a pure function of this key, so an unchanged key is an
+ * unchanged id, an unchanged feed, and unchanged invitations. Nothing is
+ * migrated because nothing moves.
+ *
+ * `/` is the separator because {@link encodeIdentityPart} percent-encodes it,
+ * so a channel whose *name* contains a slash encodes to `%2F` and can never be
+ * mistaken for the space boundary. A legacy key and a spaced key are therefore
+ * distinguishable by inspection, in both directions.
+ */
+export declare function spacedChannelNaturalKey(spaceSlug: string, channel: string): string;
+/**
+ * Which space a conversation belongs to.
+ *
+ * Read in priority order: the explicit marker, then the natural key, then the
+ * default. The fallback is not a guess -- a record with no marker was written
+ * before spaces existed, and the default space is precisely the set of things
+ * that existed before spaces. That is why this can be derived at read time
+ * instead of backfilled.
+ */
+export declare function channelSpaceSlug(conversation: ConversationIdentityRecord): string;
+/**
+ * The space named inside a natural key, or `null` when the key names none.
+ *
+ * `null` is distinct from `"home"`: it means this key carries no space at all
+ * (a direct message, a system record, a legacy channel), and the caller
+ * decides what that means. Only {@link channelSpaceSlug} turns it into the
+ * default.
+ */
+export declare function chatSpaceSlugFromNaturalKey(naturalKey: string | null | undefined): string | null;
+/**
+ * Whether a conversation record is a space rather than a room.
+ *
+ * Two independent markers have to agree. `kind: "system"` is what keeps the
+ * record out of every conversation list; the natural-key prefix is what says
+ * it is a *space* and not some other system record. Requiring both means a
+ * future system conversation cannot be mistaken for a space, and a channel
+ * cannot be mistaken for one either.
+ */
+export declare function isChatSpaceRecord(conversation: ConversationIdentityRecord): boolean;
 export declare function channelNaturalKeyFromMetadata(metadata: MetadataMap | undefined): string | null;
 /**
  * Read the semantic identity of a conversation, including the structural ids

package/dist/channel-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel-identity.d.ts","sourceRoot":"","sources":["../src/channel-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,MAAM,0BAA0B,GAAG;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,iBAAiB,SAAS,CAAC;AACxC,eAAO,MAAM,cAAc,SAAoB,CAAC;AAChD,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAC7C,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,MAAM,GAAG,OAAO,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAW3D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,OAAO,CAWpF;AAED,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,OAAO,EAAE,GAAG,MAAM,CAEzE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,WAAW,GAAG,SAAS,GAChC,MAAM,GAAG,IAAI,CAGf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,0BAA0B,GACvC,MAAM,GAAG,IAAI,CAwBf;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,0BAA0B,EAC9E,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,MAAM,GACjB,CAAC,EAAE,CAeL;AAED,wBAAgB,mCAAmC,CAAC,CAAC,SAAS,0BAA0B,EACtF,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,MAAM,GACjB,CAAC,GAAG,SAAS,CAEf"}
+{"version":3,"file":"channel-identity.d.ts","sourceRoot":"","sources":["../src/channel-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,MAAM,0BAA0B,GAAG;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,iBAAiB,SAAS,CAAC;AACxC,eAAO,MAAM,cAAc,SAAoB,CAAC;AAChD,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAC7C,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,MAAM,GAAG,OAAO,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAW3D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,OAAO,CAWpF;AAED,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,OAAO,EAAE,GAAG,MAAM,CAEzE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,SAAS,CAAC;AAE9C,0EAA0E;AAC1E,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAEvD,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAWjD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,MAAM,CAEjF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGtF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASnE;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,0BAA0B,GAAG,MAAM,CAQjF;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,MAAM,GAAG,IAAI,CAcf;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,0BAA0B,GAAG,OAAO,CAInF;AAED,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,WAAW,GAAG,SAAS,GAChC,MAAM,GAAG,IAAI,CAGf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,0BAA0B,GACvC,MAAM,GAAG,IAAI,CAwBf;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,0BAA0B,EAC9E,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,MAAM,GACjB,CAAC,EAAE,CAeL;AAED,wBAAgB,mCAAmC,CAAC,CAAC,SAAS,0BAA0B,EACtF,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,MAAM,GACjB,CAAC,GAAG,SAAS,CAEf"}

package/dist/channel-identity.js

@@ -39,6 +39,140 @@ export function namedChannelNaturalKey(channel) {
 export function systemChannelNaturalKey(name) {
     return `system:${encodeIdentityPart(name.trim().toLowerCase() || "system")}`;
 }
+/* -- spaces ---------------------------------------------------------------- */
+/**
+ * The space every channel that predates spaces belongs to.
+ *
+ * It is not a migration target; it is the name of what already exists. A
+ * channel with no space marker *is* a default-space channel, decided at read
+ * time by {@link channelSpaceSlug}, so no record is ever rewritten to acquire
+ * one.
+ */
+export const DEFAULT_CHAT_SPACE_SLUG = "home";
+/** Metadata key carrying a channel's (or a space record's) space slug. */
+export const CHANNEL_SPACE_SLUG_METADATA = "spaceSlug";
+/** Natural-key prefix for the conversation record that *is* a space. */
+export const SPACE_NATURAL_KEY_PREFIX = "space:";
+/**
+ * Slugs are the durable half of a space's identity, so they are deliberately
+ * boring: lowercase, digits and single-width hyphens, never leading or
+ * trailing punctuation. The human-readable half is the conversation `title`,
+ * which is free-form and renameable; the slug never changes once minted
+ * because it is mixed into every channel id in the space.
+ */
+const CHAT_SPACE_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+export function isChatSpaceSlug(value) {
+    return typeof value === "string" && CHAT_SPACE_SLUG_PATTERN.test(value);
+}
+/**
+ * Read a slug from untrusted input, or return `null`.
+ *
+ * Lowercasing and trimming are accepted because they cannot change which space
+ * is meant. Anything else -- a space character, a slash, a percent escape --
+ * is refused rather than repaired: silently rewriting `work/secret` into
+ * `worksecret` would resolve a request to a space the caller did not name.
+ */
+export function normalizeChatSpaceSlug(value) {
+    const candidate = typeof value === "string" ? value.trim().toLowerCase() : "";
+    return isChatSpaceSlug(candidate) ? candidate : null;
+}
+/**
+ * Derive a slug from a human title, for creation only.
+ *
+ * This one *does* rewrite, because the title is prose the operator typed and
+ * the slug is an identifier we are minting from it. It is never used to
+ * interpret a slug that arrived on a request.
+ */
+export function chatSpaceSlugFromTitle(title) {
+    const slug = title
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 32)
+        .replace(/-+$/g, "");
+    return isChatSpaceSlug(slug) ? slug : null;
+}
+/** The natural key of the conversation record that carries a space. */
+export function spaceNaturalKey(spaceSlug) {
+    return `${SPACE_NATURAL_KEY_PREFIX}${encodeIdentityPart(spaceSlug.trim().toLowerCase() || DEFAULT_CHAT_SPACE_SLUG)}`;
+}
+/**
+ * The natural key of a named channel *inside a space*.
+ *
+ * The default space returns the byte-identical legacy string, which is what
+ * keeps every channel that exists today on the exact id it already has:
+ * `stableChannelId` is a pure function of this key, so an unchanged key is an
+ * unchanged id, an unchanged feed, and unchanged invitations. Nothing is
+ * migrated because nothing moves.
+ *
+ * `/` is the separator because {@link encodeIdentityPart} percent-encodes it,
+ * so a channel whose *name* contains a slash encodes to `%2F` and can never be
+ * mistaken for the space boundary. A legacy key and a spaced key are therefore
+ * distinguishable by inspection, in both directions.
+ */
+export function spacedChannelNaturalKey(spaceSlug, channel) {
+    const slug = normalizeChatSpaceSlug(spaceSlug) ?? DEFAULT_CHAT_SPACE_SLUG;
+    const name = encodeIdentityPart(channel.trim().toLowerCase() || "shared");
+    return slug === DEFAULT_CHAT_SPACE_SLUG
+        ? namedChannelNaturalKey(channel)
+        : `channel:${slug}/${name}`;
+}
+/**
+ * Which space a conversation belongs to.
+ *
+ * Read in priority order: the explicit marker, then the natural key, then the
+ * default. The fallback is not a guess -- a record with no marker was written
+ * before spaces existed, and the default space is precisely the set of things
+ * that existed before spaces. That is why this can be derived at read time
+ * instead of backfilled.
+ */
+export function channelSpaceSlug(conversation) {
+    const declared = normalizeChatSpaceSlug(conversation.metadata?.[CHANNEL_SPACE_SLUG_METADATA]);
+    if (declared)
+        return declared;
+    const naturalKey = conversationNaturalKey(conversation);
+    return chatSpaceSlugFromNaturalKey(naturalKey) ?? DEFAULT_CHAT_SPACE_SLUG;
+}
+/**
+ * The space named inside a natural key, or `null` when the key names none.
+ *
+ * `null` is distinct from `"home"`: it means this key carries no space at all
+ * (a direct message, a system record, a legacy channel), and the caller
+ * decides what that means. Only {@link channelSpaceSlug} turns it into the
+ * default.
+ */
+export function chatSpaceSlugFromNaturalKey(naturalKey) {
+    const key = naturalKey?.trim();
+    if (!key)
+        return null;
+    if (key.startsWith(SPACE_NATURAL_KEY_PREFIX)) {
+        return normalizeChatSpaceSlug(decodeURIComponent(key.slice(SPACE_NATURAL_KEY_PREFIX.length)));
+    }
+    if (!key.startsWith("channel:"))
+        return null;
+    const rest = key.slice("channel:".length);
+    const boundary = rest.indexOf("/");
+    // No separator is a legacy key, and a legacy key is a default-space key.
+    if (boundary < 0)
+        return DEFAULT_CHAT_SPACE_SLUG;
+    return normalizeChatSpaceSlug(rest.slice(0, boundary));
+}
+/**
+ * Whether a conversation record is a space rather than a room.
+ *
+ * Two independent markers have to agree. `kind: "system"` is what keeps the
+ * record out of every conversation list; the natural-key prefix is what says
+ * it is a *space* and not some other system record. Requiring both means a
+ * future system conversation cannot be mistaken for a space, and a channel
+ * cannot be mistaken for one either.
+ */
+export function isChatSpaceRecord(conversation) {
+    if (conversation.kind !== "system")
+        return false;
+    const naturalKey = channelNaturalKeyFromMetadata(conversation.metadata);
+    return Boolean(naturalKey?.startsWith(SPACE_NATURAL_KEY_PREFIX));
+}
 export function channelNaturalKeyFromMetadata(metadata) {
     const value = metadata?.[CHANNEL_NATURAL_KEY_METADATA];
     return typeof value === "string" && value.trim() ? value.trim() : null;

package/dist/channel-invites.d.ts

@@ -0,0 +1,179 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+/**
+ * Channel invitations: a portable, scoped, revocable capability that lets a
+ * teammate bring an agent session they are *already running* into a Scout
+ * channel.
+ *
+ * Three boundaries shape this module.
+ *
+ * 1. **The secret never lands in a record.** Only `tokenHash` is persisted, so
+ *    a snapshot, a journal line, or a log dump cannot be replayed into channel
+ *    membership. The raw token exists in the invitation URL and nowhere else.
+ * 2. **Membership is not reception.** Redeeming an invitation makes an actor a
+ *    channel participant. Whether that actor can actually *receive* is a
+ *    separate, live judgement made from endpoint evidence — see
+ *    {@link deriveChannelReception}.
+ * 3. **Reachability is stated, not assumed.** A loopback route is recorded as
+ *    `local_only` so a surface can say plainly that the link will not work for
+ *    a teammate on another machine.
+ *
+ * Invites live in the owning conversation's metadata under
+ * {@link CHANNEL_INVITES_METADATA_KEY}; the broker remains the only writer.
+ */
+export declare const CHANNEL_INVITES_METADATA_KEY = "channelInvites";
+/**
+ * The only scope this pilot grants. It permits posting, reading, and replying
+ * inside one channel — never project, shell, or filesystem authority.
+ */
+export type ChannelInviteScope = "channel_participation";
+export declare const CHANNEL_INVITE_SCOPE: ChannelInviteScope;
+/** How far the recorded route actually reaches. */
+export type ChannelInviteReachability = 
+/** Loopback only: useless to anybody not on the authority machine. */
+"local_only"
+/** A LAN/mDNS doorway name or address on the local network. */
+ | "lan"
+/** A tailnet/mesh route that survives leaving the LAN. */
+ | "mesh"
+/** No evidence either way; do not claim it works. */
+ | "unknown";
+export interface ChannelInviteRoute {
+    /** The broker node that owns the channel and must accept the redemption. */
+    authorityNodeId: ScoutId;
+    /** Host an invited agent should dial. */
+    host: string;
+    /** Absolute base URL the invitation document points at. */
+    baseUrl: string;
+    reachability: ChannelInviteReachability;
+    /**
+     * Why this route may not reach the invitee. Present whenever reachability is
+     * anything but `mesh`; surfaces must render it rather than imply the link
+     * works everywhere.
+     */
+    caveat?: string;
+}
+/** One concrete agent session that accepted one invitation. */
+export interface ChannelInviteRedemption {
+    id: ScoutId;
+    /** The channel participant this redemption created or confirmed. */
+    actorId: ScoutId;
+    agentId?: ScoutId;
+    /** The pre-existing harness session attached to the channel. */
+    sessionId?: string;
+    endpointId?: ScoutId;
+    nodeId?: ScoutId;
+    harness?: string;
+    projectRoot?: string;
+    displayName?: string;
+    redeemedAt: number;
+}
+export interface ChannelInviteInvitee {
+    displayName: string;
+    handle?: string;
+    /** Set when the invitation names a durable person actor up front. */
+    actorId?: ScoutId;
+}
+export interface ChannelInviteRecord {
+    id: ScoutId;
+    channelId: ScoutId;
+    scope: ChannelInviteScope;
+    /** Lowercase hex digest of the raw token. The raw token is never stored. */
+    tokenHash: string;
+    /** A short non-secret fragment so humans can tell two invitations apart. */
+    tokenHint: string;
+    createdAt: number;
+    createdByActorId: ScoutId;
+    expiresAt: number | null;
+    maxRedemptions: number | null;
+    revokedAt?: number;
+    revokedByActorId?: ScoutId;
+    invitee?: ChannelInviteInvitee;
+    route: ChannelInviteRoute;
+    redemptions: ChannelInviteRedemption[];
+    metadata?: MetadataMap;
+}
+export type ChannelInviteState = "active" | "expired" | "revoked" | "exhausted";
+export declare function channelInviteState(invite: ChannelInviteRecord, nowMs: number): ChannelInviteState;
+export type ChannelInviteRejectionReason = "unknown_token" | "expired" | "revoked" | "exhausted" | "scope_mismatch" | "channel_mismatch" | "missing_identity";
+export interface ChannelInviteRejection {
+    reason: ChannelInviteRejectionReason;
+    message: string;
+}
+export interface ChannelInviteRedemptionRequest {
+    actorId: ScoutId;
+    agentId?: ScoutId;
+    sessionId?: string;
+    endpointId?: ScoutId;
+    nodeId?: ScoutId;
+    harness?: string;
+    projectRoot?: string;
+    displayName?: string;
+    channelId?: ScoutId;
+    scope?: string;
+}
+export type ChannelInviteRedemptionOutcome = {
+    ok: true;
+    /**
+     * The redemption already on file for this identity. Present on a retry;
+     * the caller must reuse it rather than appending a second row or
+     * consuming another slot.
+     */
+    existing: ChannelInviteRedemption | null;
+} | {
+    ok: false;
+    rejection: ChannelInviteRejection;
+};
+/**
+ * Decide whether one redemption attempt may proceed.
+ *
+ * Retries are first-class: an identity that already redeemed this invitation
+ * is accepted again with its original redemption, even once the invitation is
+ * exhausted. Re-running an agent's join command must never mint a second
+ * identity, burn a second slot, or replace a live session.
+ */
+export declare function evaluateChannelInviteRedemption(input: {
+    invite: ChannelInviteRecord;
+    request: ChannelInviteRedemptionRequest;
+    nowMs: number;
+}): ChannelInviteRedemptionOutcome;
+/**
+ * The redemption already recorded for this identity, if any.
+ *
+ * **Session identity is decisive.** When a request carries a session id, only a
+ * redemption for that exact session counts as the same joiner. A durable agent
+ * running two concrete sessions is two distinct attachments: this feature
+ * exists to attach *the exact session* a teammate is already working in, so
+ * letting a second session inherit the first one's membership through a shared
+ * agent id would hand it the wrong context and silently skip a use of the
+ * invitation.
+ *
+ * Only when no session is carried does the durable actor or agent id decide.
+ */
+export declare function findChannelInviteRedemption(invite: ChannelInviteRecord, request: Pick<ChannelInviteRedemptionRequest, "actorId" | "sessionId" | "agentId">): ChannelInviteRedemption | null;
+export declare function unknownChannelInviteRejection(): ChannelInviteRejection;
+/** Read the invitations stored on a conversation record. */
+export declare function readChannelInvites(metadata: MetadataMap | undefined): ChannelInviteRecord[];
+/** Match a presented token against stored invitations by its digest. */
+export declare function findChannelInviteByTokenHash(invites: ChannelInviteRecord[], tokenHash: string): ChannelInviteRecord | null;
+/**
+ * The public view of an invitation: everything a human or agent needs to
+ * understand the offer, and nothing that could be replayed into membership.
+ */
+export interface ChannelInvitePublicView {
+    id: ScoutId;
+    channelId: ScoutId;
+    /** Public authorship, used to show who may revoke this invitation. */
+    createdByActorId: ScoutId;
+    scope: ChannelInviteScope;
+    state: ChannelInviteState;
+    tokenHint: string;
+    createdAt: number;
+    expiresAt: number | null;
+    maxRedemptions: number | null;
+    redemptionCount: number;
+    invitee?: ChannelInviteInvitee;
+    route: ChannelInviteRoute;
+    redemptions: ChannelInviteRedemption[];
+}
+export declare function channelInvitePublicView(invite: ChannelInviteRecord, nowMs: number): ChannelInvitePublicView;
+//# sourceMappingURL=channel-invites.d.ts.map

package/dist/channel-invites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-invites.d.ts","sourceRoot":"","sources":["../src/channel-invites.ts"],"names":[],"mappings":"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"}

package/dist/channel-invites.js

@@ -0,0 +1,166 @@
+/**
+ * Channel invitations: a portable, scoped, revocable capability that lets a
+ * teammate bring an agent session they are *already running* into a Scout
+ * channel.
+ *
+ * Three boundaries shape this module.
+ *
+ * 1. **The secret never lands in a record.** Only `tokenHash` is persisted, so
+ *    a snapshot, a journal line, or a log dump cannot be replayed into channel
+ *    membership. The raw token exists in the invitation URL and nowhere else.
+ * 2. **Membership is not reception.** Redeeming an invitation makes an actor a
+ *    channel participant. Whether that actor can actually *receive* is a
+ *    separate, live judgement made from endpoint evidence — see
+ *    {@link deriveChannelReception}.
+ * 3. **Reachability is stated, not assumed.** A loopback route is recorded as
+ *    `local_only` so a surface can say plainly that the link will not work for
+ *    a teammate on another machine.
+ *
+ * Invites live in the owning conversation's metadata under
+ * {@link CHANNEL_INVITES_METADATA_KEY}; the broker remains the only writer.
+ */
+export const CHANNEL_INVITES_METADATA_KEY = "channelInvites";
+export const CHANNEL_INVITE_SCOPE = "channel_participation";
+export function channelInviteState(invite, nowMs) {
+    if (invite.revokedAt !== undefined)
+        return "revoked";
+    if (invite.expiresAt !== null && invite.expiresAt <= nowMs)
+        return "expired";
+    if (invite.maxRedemptions !== null
+        && invite.redemptions.length >= invite.maxRedemptions) {
+        return "exhausted";
+    }
+    return "active";
+}
+/**
+ * Decide whether one redemption attempt may proceed.
+ *
+ * Retries are first-class: an identity that already redeemed this invitation
+ * is accepted again with its original redemption, even once the invitation is
+ * exhausted. Re-running an agent's join command must never mint a second
+ * identity, burn a second slot, or replace a live session.
+ */
+export function evaluateChannelInviteRedemption(input) {
+    const { invite, request, nowMs } = input;
+    const actorId = request.actorId?.trim();
+    if (!actorId) {
+        return {
+            ok: false,
+            rejection: {
+                reason: "missing_identity",
+                message: "Redemption needs the actor id of the agent session that is joining.",
+            },
+        };
+    }
+    if (request.channelId?.trim() && request.channelId.trim() !== invite.channelId) {
+        return {
+            ok: false,
+            rejection: {
+                reason: "channel_mismatch",
+                message: "This invitation does not belong to the requested channel.",
+            },
+        };
+    }
+    if (request.scope?.trim() && request.scope.trim() !== invite.scope) {
+        return {
+            ok: false,
+            rejection: {
+                reason: "scope_mismatch",
+                message: `This invitation grants ${invite.scope} only.`,
+            },
+        };
+    }
+    const existing = findChannelInviteRedemption(invite, request);
+    if (existing) {
+        // Revocation still bites: a revoked invitation stops being a usable
+        // capability even for an identity that once held it.
+        if (invite.revokedAt !== undefined) {
+            return { ok: false, rejection: channelInviteRejection("revoked") };
+        }
+        return { ok: true, existing };
+    }
+    const state = channelInviteState(invite, nowMs);
+    if (state !== "active") {
+        return { ok: false, rejection: channelInviteRejection(state) };
+    }
+    return { ok: true, existing: null };
+}
+/**
+ * The redemption already recorded for this identity, if any.
+ *
+ * **Session identity is decisive.** When a request carries a session id, only a
+ * redemption for that exact session counts as the same joiner. A durable agent
+ * running two concrete sessions is two distinct attachments: this feature
+ * exists to attach *the exact session* a teammate is already working in, so
+ * letting a second session inherit the first one's membership through a shared
+ * agent id would hand it the wrong context and silently skip a use of the
+ * invitation.
+ *
+ * Only when no session is carried does the durable actor or agent id decide.
+ */
+export function findChannelInviteRedemption(invite, request) {
+    const sessionId = request.sessionId?.trim();
+    if (sessionId) {
+        return invite.redemptions.find((redemption) => redemption.sessionId?.trim() === sessionId) ?? null;
+    }
+    const actorId = request.actorId?.trim();
+    const agentId = request.agentId?.trim();
+    return invite.redemptions.find((redemption) => {
+        if (actorId && redemption.actorId === actorId)
+            return true;
+        return Boolean(agentId) && redemption.agentId?.trim() === agentId;
+    }) ?? null;
+}
+function channelInviteRejection(state) {
+    switch (state) {
+        case "expired":
+            return { reason: "expired", message: "This invitation has expired. Ask for a new one." };
+        case "revoked":
+            return { reason: "revoked", message: "This invitation was revoked." };
+        case "exhausted":
+            return {
+                reason: "exhausted",
+                message: "This invitation has already been used the maximum number of times.",
+            };
+    }
+}
+export function unknownChannelInviteRejection() {
+    // Deliberately identical for a malformed, unknown, and deleted token: a
+    // probe must not learn which invitations exist.
+    return { reason: "unknown_token", message: "This invitation link is not valid." };
+}
+/** Read the invitations stored on a conversation record. */
+export function readChannelInvites(metadata) {
+    const raw = metadata?.[CHANNEL_INVITES_METADATA_KEY];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((entry) => Boolean(entry)
+        && typeof entry === "object"
+        && typeof entry.id === "string"
+        && typeof entry.tokenHash === "string"
+        && Array.isArray(entry.redemptions));
+}
+/** Match a presented token against stored invitations by its digest. */
+export function findChannelInviteByTokenHash(invites, tokenHash) {
+    const normalized = tokenHash.trim().toLowerCase();
+    if (!normalized)
+        return null;
+    return invites.find((invite) => invite.tokenHash.toLowerCase() === normalized) ?? null;
+}
+export function channelInvitePublicView(invite, nowMs) {
+    return {
+        id: invite.id,
+        channelId: invite.channelId,
+        createdByActorId: invite.createdByActorId,
+        scope: invite.scope,
+        state: channelInviteState(invite, nowMs),
+        tokenHint: invite.tokenHint,
+        createdAt: invite.createdAt,
+        expiresAt: invite.expiresAt,
+        maxRedemptions: invite.maxRedemptions,
+        redemptionCount: invite.redemptions.length,
+        ...(invite.invitee ? { invitee: invite.invitee } : {}),
+        route: invite.route,
+        redemptions: invite.redemptions,
+    };
+}