ahp-channels 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tyler Leonhardt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISHING.md

@@ -0,0 +1,76 @@
+# Publishing
+
+`ahp-channels` uses the same tag-driven npm release model as
+[`TylerLeonhardt/ahpx`](https://github.com/TylerLeonhardt/ahpx).
+
+Pushing `vX.Y.Z` runs [publish.yml](./.github/workflows/publish.yml). The
+workflow publishes the version already committed in `package.json`; it never
+bumps versions itself.
+
+## Bootstrap the package once
+
+The package must exist on npm before its trusted publisher can be configured.
+From a trusted machine:
+
+```powershell
+npm adduser
+cd C:\path\to\ahp-channels
+npm run check
+npm run test:package
+npm publish --tag next --provenance=false
+```
+
+The local bootstrap disables provenance because it does not run in an OIDC
+environment. All later workflow publishes use trusted publishing and generate
+provenance automatically.
+
+Then open npmjs.com → `ahp-channels` → Settings → Trusted Publisher and set:
+
+- Provider: GitHub Actions
+- Owner: `TylerLeonhardt`
+- Repository: `ahp-channels`
+- Workflow: `publish.yml`
+- Environment: leave blank
+
+After confirming one OIDC release, set Publishing access to **Require 2FA and
+disallow tokens**.
+
+## Cut subsequent releases
+
+```powershell
+# Choose the intended version explicitly.
+npm version prerelease --preid alpha --no-git-tag-version
+# Or: npm version patch|minor|major --no-git-tag-version
+
+$version = node -p "require('./package.json').version"
+git add package.json package-lock.json src/version.ts
+git commit -m "Bump version to $version"
+git push origin main
+git tag -a "v$version" -m "v$version"
+git push origin "v$version"
+```
+
+The `npm version` lifecycle synchronizes `src/version.ts`, and the build fails
+if it does not match `package.json`. The package smoke test verifies the CLI and
+tarball versions; the publish workflow separately verifies the git tag.
+
+Prerelease versions publish under npm's `next` tag. Stable versions publish
+under `latest`.
+
+Watch the release:
+
+```powershell
+gh run watch
+npm view ahp-channels dist-tags --json
+```
+
+## Pipeline guarantees
+
+The workflow:
+
+1. Rejects a tag that differs from `package.json`.
+2. Runs type checking, unit tests, and the build.
+3. Installs and exercises the packed npm artifact.
+4. Rejects versions already present on npm.
+5. Publishes through npm OIDC trusted publishing.
+6. Creates a matching GitHub Release.

package/README.md

@@ -0,0 +1,96 @@
+# ahp-channels
+
+Run Claude Code channel plugins against any Agent Host Protocol server.
+
+`ahp-channels` is an experimental compatibility adapter. It launches a
+Claude-style MCP channel plugin, forwards inbound channel notifications to an
+AHP chat, and exposes the plugin's MCP tools as AHP client tools.
+
+## Quick start
+
+```powershell
+npm install
+npm run build
+
+node .\dist\cli.js plugin install telegram@claude-plugins-official
+node .\dist\cli.js host discover
+node .\dist\cli.js session list
+node .\dist\cli.js channel create telegram --plugin telegram --session <session-uri>
+node .\dist\cli.js channel secret set telegram TELEGRAM_BOT_TOKEN
+node .\dist\cli.js channel start telegram
+```
+
+The CLI stores configuration under `~/.ahp-channels` by default. Override this
+with `AHP_CHANNELS_HOME`.
+
+Telegram currently requires Bun, matching the upstream plugin. The adapter
+supports standalone TCP hosts and normal editor Agent Hosts over Windows named
+pipes or Unix domain sockets.
+
+DM the bot once it starts, then approve and lock down the sender locally:
+
+```powershell
+ahp-channels channel access status telegram
+ahp-channels channel access pair telegram <code>
+ahp-channels channel access policy telegram allowlist
+```
+
+Secrets are stored in Windows Credential Manager, macOS Keychain, or a
+persistent Linux Secret Service. Named instances receive isolated plugin state under
+`~/.ahp-channels/instances/<name>`.
+
+## Status
+
+The compatibility bridge and durable daemon control milestones are complete.
+See [ROADMAP.md](./ROADMAP.md) for the remaining setup, reliability, and
+distribution work.
+
+## Manage a channel
+
+```powershell
+ahp-channels channel status telegram
+ahp-channels channel switch telegram --session <new-session-uri>
+ahp-channels channel stop telegram
+ahp-channels channel start telegram
+ahp-channels channel delete telegram
+```
+
+The daemon starts on demand, remembers desired running channels, and restarts
+them after a daemon or channel-process restart. A switch is rejected while the
+channel is processing a turn, so an in-flight reply is never silently orphaned.
+Inbound events with stable platform IDs are journaled before AHP dispatch and
+deduplicated across process restarts.
+
+Deleting a channel also removes its keyring entries and isolated state,
+including allowlists, downloaded attachments, and pending event data.
+
+```powershell
+ahp-channels daemon status
+ahp-channels daemon logs
+ahp-channels daemon stop
+ahp-channels daemon start
+```
+
+Control traffic uses a per-install random token over a local named pipe on
+Windows or a mode-`0600` Unix socket. Configuration writes are atomic and use a
+heartbeat-backed cross-process lock.
+
+For one-off foreground use, `channel run` remains available:
+
+```powershell
+ahp-channels channel run telegram --session <session-uri>
+```
+
+## Development
+
+```powershell
+npm test
+npm run typecheck
+npm run build
+npm run test:package
+npm run e2e:local
+npm run e2e:daemon
+```
+
+See [SHIPPING.md](./SHIPPING.md) for the npm prerelease gates and
+[PUBLISHING.md](./PUBLISHING.md) for the tag-driven release process.

package/ROADMAP.md

@@ -0,0 +1,46 @@
+# Roadmap
+
+## Completed: Runnable compatibility bridge
+
+- Install relative-path plugins from Claude-style Git marketplaces.
+- Discover local VS Code Agent Host endpoints.
+- List sessions on a discovered host.
+- Run one stdio MCP channel against one existing AHP chat.
+- Translate channel notifications and client-owned tool calls.
+- Verify against a live local Agent Host.
+
+## Completed: Durable channel control
+
+- Named instances with persistent channel-to-session bindings.
+- Authenticated background daemon with start, stop, status, switch, and logs.
+- Desired-state restoration and bounded exponential restart retries.
+- Busy-session switch protection and failed-switch rollback.
+- Atomic cross-process configuration updates.
+
+## Completed: Alpha reliability gates
+
+- Normal editor endpoints over Windows named pipes and Unix sockets.
+- OS-keyring secrets with environment-only injection into channel processes.
+- Named instances with isolated state directories.
+- Durable event IDs, pending replay, and bounded deduplication history.
+- First-class secret and Telegram access commands.
+
+## Next: Operational polish
+
+- Log rotation and richer health diagnostics.
+- Stable aliases for explicitly selected remote Agent Hosts.
+- Additional channel-specific configuration profiles.
+
+## Later: Broader compatibility
+
+- Permission relay with sanitized previews and expiring request IDs.
+- Git subdirectory, URL, npm, and pip marketplace sources.
+- Virtual plugin projection for channel instructions and management skills.
+- Attachment and resource-reference translation.
+
+## Later: Governance and distribution
+
+- Signed or pinned marketplace policy.
+- Runtime-enforced channel and permission-relay allowlists.
+- OS credential-store integrations.
+- Packaged binaries and service installation.

package/SHIPPING.md

@@ -0,0 +1,24 @@
+# Shipping checklist
+
+## `0.1.0-alpha.1`
+
+- [x] Claude-style MCP channel compatibility.
+- [x] TCP, Windows named-pipe, and Unix-socket Agent Host connections.
+- [x] Named instances with daemon start, stop, restart, status, and switch.
+- [x] OS-keyring secrets and isolated instance state.
+- [x] Durable event replay and deduplication.
+- [x] Windows and Linux CI.
+- [x] Installed-package smoke test.
+- [x] Live direct bridge and two-session daemon switch tests.
+- [x] Confirm the `ahp-channels` npm package name is available.
+- [x] Choose and add the repository license (MIT).
+- [x] Add the tag-driven OIDC publish workflow and release documentation.
+- [ ] Bootstrap the package and configure npm trusted publishing for `TylerLeonhardt/ahp-channels`.
+- [ ] Run a fresh-machine Telegram setup on macOS or Linux.
+- [ ] Publish `0.1.0-alpha.1` under the npm `next` tag.
+
+## `0.1.0`
+
+- [ ] Soak the alpha with Telegram and fakechat.
+- [ ] Add log rotation and actionable health diagnostics.
+- [ ] Resolve alpha feedback and document compatibility limits.

package/dist/ahp.d.ts

@@ -0,0 +1,17 @@
+import { type InitializeResult, type SessionState, type SessionSummary } from '@microsoft/agent-host-protocol';
+import { AhpClient, type Subscription } from '@microsoft/agent-host-protocol/client';
+import type { AgentHostEndpoint } from './endpoints.js';
+export interface ConnectedAgentHost {
+    readonly client: AhpClient;
+    readonly clientId: string;
+    readonly initializeResult: InitializeResult;
+}
+export interface SubscribedSession {
+    readonly state: SessionState;
+    readonly subscription: Subscription;
+}
+export declare function createChannelClientId(plugin: string, session: string): string;
+export declare function connectAgentHost(endpoint: AgentHostEndpoint, clientId?: string): Promise<ConnectedAgentHost>;
+export declare function listSessions(client: AhpClient): Promise<readonly SessionSummary[]>;
+export declare function subscribeSession(client: AhpClient, session: string): Promise<SubscribedSession>;
+export declare function resolveChat(state: SessionState, requested?: string, session?: string): string;

package/dist/ahp.js

@@ -0,0 +1,70 @@
+import { SUPPORTED_PROTOCOL_VERSIONS, } from '@microsoft/agent-host-protocol';
+import { AhpClient } from '@microsoft/agent-host-protocol/client';
+import { WebSocketTransport } from '@microsoft/agent-host-protocol/ws';
+import { createHash, randomUUID } from 'node:crypto';
+import { SocketWebSocketTransport } from './socketWebSocketTransport.js';
+export function createChannelClientId(plugin, session) {
+    const digest = createHash('sha256')
+        .update('ahp-channels\0')
+        .update(plugin)
+        .update('\0')
+        .update(session)
+        .digest('hex');
+    return `${digest.slice(0, 8)}-${digest.slice(8, 12)}-${digest.slice(12, 16)}-${digest.slice(16, 20)}-${digest.slice(20, 32)}`;
+}
+export async function connectAgentHost(endpoint, clientId = randomUUID()) {
+    const transport = endpoint.endpoint.type === 'tcp'
+        ? await connectTcp(endpoint)
+        : await SocketWebSocketTransport.connect(endpoint.endpoint.path, endpoint.connectionToken);
+    const client = new AhpClient(transport);
+    client.connect();
+    try {
+        const initializeResult = await client.initialize({
+            clientId,
+            protocolVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+            initialSubscriptions: ['ahp-root://'],
+        });
+        return { client, clientId, initializeResult };
+    }
+    catch (error) {
+        await client.shutdown();
+        throw error;
+    }
+    async function connectTcp(endpoint) {
+        if (endpoint.endpoint.type !== 'tcp') {
+            throw new Error('Expected a TCP Agent Host endpoint');
+        }
+        const url = new URL(`ws://${endpoint.endpoint.host}:${endpoint.endpoint.port}/`);
+        url.searchParams.set('tkn', endpoint.connectionToken);
+        return WebSocketTransport.connect(url);
+    }
+}
+export async function listSessions(client) {
+    const result = await client.request('listSessions', { channel: 'ahp-root://' });
+    return result.items;
+}
+export async function subscribeSession(client, session) {
+    const { result, subscription } = await client.subscribe(session);
+    if (!result.snapshot) {
+        await subscription.close();
+        throw new Error(`Agent Host returned no state snapshot for session ${session}`);
+    }
+    return {
+        state: result.snapshot.state,
+        subscription,
+    };
+}
+export function resolveChat(state, requested, session = 'session') {
+    if (requested) {
+        const known = state.chats.some(chat => chat.resource === requested);
+        if (!known) {
+            throw new Error(`Chat ${requested} does not belong to ${session}`);
+        }
+        return requested;
+    }
+    const chat = state.defaultChat ?? state.chats[0]?.resource;
+    if (!chat) {
+        throw new Error(`${session} has no chat`);
+    }
+    return chat;
+}

package/dist/bridge.d.ts

@@ -0,0 +1,52 @@
+import { type ChatState, type ChatToolCallReadyAction, type StateAction } from '@microsoft/agent-host-protocol';
+import type { DispatchHandle, SubscriptionEvent } from '@microsoft/agent-host-protocol/client';
+import { type ChannelEventJournal } from './eventJournal.js';
+import type { McpChannelClient, StartedMcpChannel } from './mcpChannel.js';
+export interface ChannelBridgeOptions {
+    readonly client: {
+        dispatch(channel: string, action: StateAction, clientSeq?: number): DispatchHandle;
+        unsubscribe?(channel: string): Promise<void>;
+    };
+    readonly clientId: string;
+    readonly session: string;
+    readonly chat: string;
+    readonly chatState: ChatState;
+    readonly chatSubscription: AsyncIterable<SubscriptionEvent> & {
+        close(): Promise<void>;
+    };
+    readonly channel: Pick<McpChannelClient, 'setChannelHandler' | 'callTool' | 'close'>;
+    readonly channelInfo: StartedMcpChannel;
+    readonly eventJournal?: ChannelEventJournal;
+    readonly autoApproveTools?: boolean;
+    readonly onStatus?: (message: string) => void;
+}
+export declare class ChannelBridge {
+    private readonly options;
+    private activeTurnId;
+    private readonly queuedMessageIds;
+    private readonly pendingTools;
+    private readonly inFlightEventHandlers;
+    private actionLoop;
+    private acceptingEvents;
+    private closed;
+    private eventFailureSignalled;
+    private resolveEventFailure;
+    private readonly eventFailure;
+    constructor(options: ChannelBridgeOptions);
+    get busy(): boolean;
+    get whenStopped(): Promise<void>;
+    quiesce(): Promise<boolean>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private handleChannelEvent;
+    private trackChannelEvent;
+    private drainEventHandlers;
+    private dispatchChannelEvent;
+    private consumeChatActions;
+    private handleAction;
+    private trackToolStart;
+    private trackToolReady;
+    private executeTool;
+    private dispatchToolCompletion;
+}
+export declare function parseToolInput(input: ChatToolCallReadyAction['toolInput']): Record<string, unknown>;