@ctliz/agent-intercom-codex 0.11.0-connect.2

package/skills/codex-intercom/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: codex-intercom
+description: |
+  Coordinate with local Pi or Codex sessions through pi-intercom MCP tools.
+  Use for same-machine planner-worker workflows, direct peer questions,
+  cross-session context sharing, and checking or replying to pending asks.
+---
+
+# Codex Intercom
+
+Use this skill when you need to coordinate with another local coding-agent
+session through the `pi-intercom` MCP server.
+
+Codex cannot currently receive unsolicited MCP messages as a fresh visible turn.
+Inbound messages are queued by the MCP server while it is running. Check
+`intercom_pending` at natural boundaries, before starting delegated work, and
+when you expect a response.
+
+If the user needs wake-on-message behavior, use or recommend the app-server
+bridge daemon. It exposes configured virtual Codex workers as intercom sessions;
+messages to those workers create or resume app-server threads and start turns.
+
+## Tools
+
+- `intercom_whoami`: show this session's intercom ID, name, cwd, and model.
+- `intercom_team`: show the current orchestrator manager and live same-manager coworkers.
+- `intercom_status`: check connection, active session count, unread messages,
+  and unresolved inbound asks.
+- `intercom_list`: list connected Pi and Codex sessions.
+- `intercom_set_summary`: publish a short discoverable status.
+- `intercom_send`: fire-and-forget direct message.
+- `intercom_ask`: send a question and wait for the target's reply.
+- `intercom_pending`: read queued inbound messages and pending asks.
+- `intercom_reply`: reply to a pending inbound ask.
+
+## Workflow
+
+1. Call `intercom_status` or `intercom_whoami` to verify this session is
+   connected.
+2. Call `intercom_set_summary` with a concise status when other sessions need
+   to discover your role.
+3. If this is an orchestrator-owned coworker, call `intercom_team` to get the manager and sibling targets without searching globally. Otherwise use `intercom_list`.
+4. Use `intercom_send` for non-blocking updates and handoffs.
+5. Use `intercom_ask` only when you need the answer before continuing. Assignments, progress/status checkpoints, notifications, and completion reports use `intercom_send`.
+6. Call `intercom_pending` before ending a coordination turn, then answer
+   blocking asks with `intercom_reply`.
+
+## Patterns
+
+Planner delegates without waiting:
+
+```typescript
+intercom_send({
+  to: "worker",
+  message: "Task-3: Add retry logic in src/api/client.ts. Ask if the retry scope is unclear."
+})
+```
+
+Worker asks and waits:
+
+```typescript
+intercom_ask({
+  to: "planner",
+  message: "Should retry apply only to idempotent endpoints? Proposed: GET/PUT/DELETE, max 3, exponential backoff."
+})
+```
+
+Reply to an inbound ask:
+
+```typescript
+intercom_pending({ mark_read: false })
+intercom_reply({ message: "Use GET/PUT/DELETE only, max 3 retries." })
+```
+
+When multiple asks are pending, select the sender with `to`. If that sender has multiple unresolved asks, select `oldest` or `latest` without using protocol IDs:
+
+```typescript
+intercom_reply({
+  to: "planner",
+  which: "oldest",
+  message: "Proceed, but preserve the public error shape."
+})
+```
+
+Keep at most one unresolved `intercom_ask` to the same recipient. Use `intercom_send` for non-blocking follow-ups and every progress/status request.
+
+Wake a bridge-managed worker:
+
+```typescript
+intercom_ask({
+  to: "codex-worker",
+  message: "Please inspect the failing test and reply with the most likely cause."
+})
+```
+
+## Boundaries
+
+- Do not assume push delivery into Codex. Check `intercom_pending`.
+- Do not assume a normal MCP session can wake itself from idle. Use the
+  app-server bridge for wake-on-message virtual workers.
+- Do not use `intercom_ask` for passive polling of files, ports, or process
+  completion. Use normal shell checks for those.
+- Keep messages concise and include file paths, command output summaries, and
+  decision options when useful.

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "target": "ES2022",
+    "types": ["node"]
+  },
+  "include": ["*.ts", "broker/**/*.ts", "codex/**/*.ts", "protocol-v4/**/*.ts", "provider/**/*.ts"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}

package/types.ts

@@ -0,0 +1,225 @@
+import type {
+  BossControlEnvelope,
+  BossParticipantBinding,
+  BossParticipantCredentialEnvelope,
+  BossRunFeatureContract,
+  BrokerCapabilityAdvertisement,
+  ParticipantState,
+  WorkerIdentityV2,
+} from "@ctliz/agent-intercom-core/boss";
+
+export interface BossParticipantRegistrationMetadata {
+  featureContract: BossRunFeatureContract;
+  credential: BossParticipantCredentialEnvelope;
+}
+
+/** Broker-owned metadata. Clients may request Boss registration but never assert a binding. */
+export interface BossParticipantBindingMetadata {
+  featureContract: BossRunFeatureContract;
+  binding: BossParticipantBinding;
+  brokerIdentityVerified: true;
+  assignedParticipantIds?: string[];
+  requestingPrincipalId?: string;
+  /** Required by Boss roster projection before a session is discoverable. */
+  workerIdentity?: WorkerIdentityV2;
+  participantState?: ParticipantState;
+}
+
+export interface SessionInfo {
+  id: string;
+  name?: string;
+  cwd: string;
+  model: string;
+  pid: number;
+  startedAt: number;
+  lastActivity: number;
+  status?: string;
+  peerUid?: number;
+  trustedLocal?: boolean;
+  origin?: "local" | "remote";
+  remoteHostId?: string;
+  parentSessionId?: string;
+  rootSessionId?: string;
+  generation?: number;
+  canDelegate?: boolean;
+  depth?: number;
+  maxDepth?: number;
+  maxChildren?: number;
+  boss?: BossParticipantBindingMetadata;
+}
+
+export interface Message {
+  id: string;
+  timestamp: number;
+  replyTo?: string;
+  expectsReply?: boolean;
+  content: {
+    text: string;
+    attachments?: Attachment[];
+  };
+}
+
+export interface Attachment {
+  type: "file" | "snippet" | "context";
+  name: string;
+  content: string;
+  language?: string;
+}
+
+type SessionRegistrationBase = Omit<
+  SessionInfo,
+  "id" | "peerUid" | "trustedLocal" | "origin" | "remoteHostId" | "parentSessionId" | "rootSessionId" | "generation" | "canDelegate" | "depth" | "maxDepth" | "maxChildren" | "boss"
+> & {
+  /** Ephemeral identity shared only by reconnects from one live runtime. */
+  runtimeInstanceId?: string;
+};
+
+export type OrdinarySessionRegistration = SessionRegistrationBase & {
+  boss?: never;
+};
+
+export type BossSessionRegistration = SessionRegistrationBase & {
+  /** Optional untrusted request; only a protected, attested broker may return a binding. */
+  boss: BossParticipantRegistrationMetadata;
+};
+
+export type SessionRegistration = OrdinarySessionRegistration | BossSessionRegistration;
+
+export interface RemoteEnrollmentAccess {
+  enrollmentToken: string;
+}
+
+export interface RemoteSessionAccess {
+  sessionCredential: string;
+  sessionId: string;
+  generation: number;
+}
+
+export type RemoteRegistrationAccess = RemoteEnrollmentAccess | RemoteSessionAccess;
+
+export interface RemoteAccessMetadata {
+  origin: "remote";
+  remoteHostId: string;
+  parentSessionId: string;
+  rootSessionId: string;
+  generation: number;
+  canDelegate: boolean;
+  depth: number;
+  maxDepth: number;
+  maxChildren: number;
+  sessionCredential?: string;
+}
+
+export interface RemotePrincipalSummary {
+  id: string;
+  name: string;
+  parentSessionId: string;
+  rootSessionId: string;
+  remoteHostId: string;
+  generation: number;
+  policy: "remote-tree";
+  canDelegate: boolean;
+  depth: number;
+  maxDepth: number;
+  maxChildren: number;
+  state: "active" | "revoked";
+  expiresAt: number;
+  createdAt: number;
+  updatedAt: number;
+  connected: boolean;
+}
+
+export interface RemoteAccessContract {
+  feature: "remote-access-v1";
+  policySemanticsVersion: number;
+  policySemanticsHash: string;
+}
+
+export type DeliveryFailureCode =
+  | "INVALID_MESSAGE"
+  | "SESSION_NOT_FOUND"
+  | "AMBIGUOUS_TARGET"
+  | "SENDER_NOT_FOUND"
+  | "INVALID_REPLY_TARGET"
+  | "MUTUAL_ASK"
+  | "ASK_ALREADY_PENDING"
+  | "DUPLICATE_MESSAGE_ID"
+  | "CONFLICTING_MESSAGE_ID"
+  | "TOO_MANY_PENDING_DELIVERIES"
+  | "TOO_MANY_PENDING_ASKS"
+  | "RECIPIENT_DISCONNECTED"
+  | "SENDER_DISCONNECTED"
+  | "DELIVERY_TIMEOUT";
+
+export type BossControlFailureCode =
+  | "INVALID_CONTROL"
+  | "IDEMPOTENCY_CONFLICT"
+  | "SESSION_NOT_FOUND"
+  | "POLICY_DENIED"
+  | "RECIPIENT_DISCONNECTED"
+  | "DELIVERY_TIMEOUT";
+
+export type BrokerErrorCode =
+  | "PROTOCOL_MISMATCH"
+  | "INVALID_REQUEST"
+  | "SESSION_ID_IN_USE"
+  | "ACCESS_DENIED"
+  | "REMOTE_ACCESS_INCOMPATIBLE"
+  | "BOSS_FEATURE_UNAVAILABLE"
+  | "BOSS_CONTRACT_MISMATCH"
+  | "RATE_LIMITED"
+  | "TOO_MANY_SESSIONS";
+
+export type AskCancellationReason =
+  | "cancelled"
+  | "expired"
+  | "delivery_failed"
+  | "session_disconnected"
+  | "authorization_revoked";
+
+export type ClientMessage =
+  | { type: "health"; requestId: string; stateId?: string }
+  | { type: "register"; protocol: string; version: number; session: OrdinarySessionRegistration; sessionId?: string; stateId?: string; access?: RemoteRegistrationAccess; scopeId?: string }
+  | { type: "register"; registrationKind: "boss"; protocol: string; version: number; session: BossSessionRegistration; sessionId?: string; stateId?: string; access?: never; scopeId?: string }
+  | { type: "access_control"; requestId: string; adminToken: string; action: "issue_enrollment"; enrollment: { name: string; parentSessionId: string; rootSessionId: string; remoteHostId: string; ttlMs?: number; expiresAt?: number; canDelegate?: boolean; maxDepth?: number; maxChildren?: number } }
+  | { type: "access_control"; requestId: string; adminToken: string; action: "revoke_subtree"; principalId: string }
+  | { type: "access_control"; requestId: string; adminToken: string; action: "inspect_tree"; principalId: string }
+  | { type: "access_control"; requestId: string; adminToken: string; action: "adopt_subtree"; principalId: string; newParentSessionId: string }
+  | { type: "access_control"; requestId: string; access: RemoteSessionAccess; action: "issue_child_enrollment"; enrollment: { name: string; ttlMs?: number; expiresAt?: number; canDelegate?: boolean; maxDepth?: number; maxChildren?: number } }
+  | { type: "access_control"; requestId: string; access: RemoteSessionAccess; action: "inspect_tree"; principalId?: string }
+  | { type: "unregister"; preserveAsks?: boolean }
+  | { type: "list"; requestId: string }
+  | { type: "send"; to: string; message: Message }
+  | { type: "boss_control"; requestId: string; to: string; envelope: BossControlEnvelope }
+  | { type: "boss_control_received"; deliveryId: string; messageId: string; idempotencyKey: string }
+  | { type: "message_received"; deliveryId: string }
+  | { type: "message_rejected"; deliveryId: string; code: "CONFLICTING_MESSAGE_ID"; reason: string }
+  | { type: "defer_ask"; requestId: string; messageId: string }
+  | { type: "cancel_ask"; requestId: string; messageId: string }
+  | { type: "presence"; name?: string; status?: string; model?: string };
+
+export type BrokerMessage =
+  | { type: "health_ok"; requestId: string; protocol: string; version: number; endpoint: "local" | "remote"; remoteAccess?: RemoteAccessContract; capabilities?: BrokerCapabilityAdvertisement }
+  | { type: "registered"; sessionId: string; protocol: string; version: number; remoteAccess?: RemoteAccessContract; access?: RemoteAccessMetadata }
+  | { type: "registered"; registrationKind: "boss"; sessionId: string; protocol: string; version: number; capabilities: BrokerCapabilityAdvertisement; boss: BossParticipantBindingMetadata; remoteAccess?: never; access?: never }
+  | { type: "access_control_result"; requestId: string; action: "issue_enrollment"; enrollmentToken: string; expiresAt: number }
+  | { type: "access_control_result"; requestId: string; action: "revoke_subtree"; changedPrincipalIds: string[] }
+  | { type: "access_control_result"; requestId: string; action: "inspect_tree"; principals: RemotePrincipalSummary[] }
+  | { type: "access_control_result"; requestId: string; action: "adopt_subtree"; principals: RemotePrincipalSummary[] }
+  | { type: "access_control_result"; requestId: string; action: "issue_child_enrollment"; enrollmentToken: string; expiresAt: number; parentSessionId: string }
+  | { type: "sessions"; requestId: string; sessions: SessionInfo[] }
+  | { type: "message"; deliveryId: string; from: SessionInfo; message: Message }
+  | { type: "boss_control"; deliveryId: string; from: SessionInfo; envelope: BossControlEnvelope }
+  | { type: "boss_control_ack"; requestId: string; messageId: string; idempotencyKey: string; status: "accepted"; deliveryId: string }
+  | { type: "boss_control_result"; requestId: string; messageId: string; idempotencyKey: string; status: "delivered"; delivered: true; deliveryId: string }
+  | { type: "boss_control_result"; requestId: string; messageId: string; idempotencyKey: string; status: "rejected"; delivered: false; deliveryId?: string; code: BossControlFailureCode; reason: string }
+  | { type: "presence_update"; session: SessionInfo }
+  | { type: "session_joined"; session: SessionInfo }
+  | { type: "session_left"; sessionId: string }
+  | { type: "error"; code: BrokerErrorCode; error: string }
+  | { type: "delivery_accepted"; messageId: string; deliveryId: string }
+  | { type: "delivered"; messageId: string; deliveryId: string }
+  | { type: "delivery_failed"; messageId: string; accepted: boolean; code: DeliveryFailureCode; reason: string }
+  | { type: "ask_deferred"; messageId: string; fromSessionId: string }
+  | { type: "ask_cancelled"; messageId: string; fromSessionId: string; reason: AskCancellationReason }
+  | { type: "ask_control_result"; requestId: string; action: "defer" | "cancel"; messageId: string; applied: boolean };