@krischoichoi/channel-core 0.0.0-stage → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wsz987
+
+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/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @krischoichoi/channel-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Stable cross-channel contract and Cordis `ChannelService` for DeepSeek Harness Channels.
+
+`channel-core` is the foundation of the `dsh-channels` monorepo. It defines the
+**Channel Contract** that every adapter implements, and the shared runtime
+service mounted at `ctx.channels`. It never imports Harness Agent APIs and never
+depends on a concrete messaging platform.
+
+## Install
+
+```bash
+pnpm add @krischoichoi/channel-core
+```
+
+As a Cordis plugin:
+
+```yaml
+- id: channels-service
+  name: '@krischoichoi/channel-core/plugin'
+```
+
+## What's inside
+
+| Export | Purpose |
+| --- | --- |
+| `ChannelAdapter` / `defineChannelAdapter` | The adapter contract and the third-party authoring helper |
+| `ChannelService` (`ctx.channels`) | Adapter registry, typed event bus, shared secrets/storage resources |
+| `ChannelCapabilities` | Capability negotiation (`text`, `image`, `file`, `streaming`, …) |
+| `ChannelTarget` / `OutboundMessage` / `SendResult` / `ReplyHandle` | Structured messaging types |
+| `ChannelEvent` / `AuthChallenge` / `ChannelHealth` | Event, auth and health surfaces |
+| `ChannelError` / `isChannelError` | Stable machine-readable error hierarchy |
+| `mountChannelAdapter` | Transactional mount lifecycle (register → start → stop → unregister) |
+| `ChannelRuntimeResources` | Durable secrets and storage shared by all mounted adapters |
+| media helpers | `SecureRemoteMediaFetcher`, `RemotePolicy`, bounded response readers |
+
+## Quick start
+
+```ts
+import { defineChannelAdapter } from '@krischoichoi/channel-core';
+
+export default defineChannelAdapter({
+  id: 'my-channel',
+  capabilities: {
+    text: true,
+    image: false,
+    file: false,
+    audio: false,
+    video: false,
+    markdown: false,
+    cards: false,
+    reactions: false,
+    threads: false,
+    streaming: 'buffered', // 'native' | 'edit' | 'buffered'
+  },
+  async start(ctx) {
+    // connect the platform, then emit messages with ctx.emit('message', ...)
+  },
+  async stop() {
+    // idempotent cleanup
+  },
+  async send(target, message) {
+    // send one OutboundMessage
+  },
+});
+```
+
+In production the plugin wires file-backed resources automatically; in tests the
+service falls back to in-memory stores:
+
+```ts
+import { Context } from '@deepseek-ai/cordis';
+import { ChannelService } from '@krischoichoi/channel-core';
+
+const ctx = new Context();
+const channels = new ChannelService(ctx);
+
+channels.register(adapter);
+channels.on((event) => console.log(event.type));
+```
+
+## Data directory
+
+The plugin resolves the durable data directory in this order:
+
+1. `DSH_CHANNELS_DATA_DIR` (explicit override)
+2. `<Harness home>/dsh-channels` (`$DSH_HOME`, else `~/.dsh`)
+
+## Development
+
+```bash
+pnpm --filter @krischoichoi/channel-core build
+pnpm --filter @krischoichoi/channel-core typecheck
+pnpm --filter @krischoichoi/channel-core test
+```
+
+## Related
+
+- [Repository root](../../README.md)
+- [Adapter authoring guide](../../docs/adapter-authoring.md)
+
+## License
+
+[MIT](../../LICENSE)

package/lib/access.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Channel Access Policy — the shared, versioned, cross-package contract for
+ * inbound access control.
+ *
+ * This module defines ONLY stable cross-package semantics:
+ *
+ * - the `ChannelAccessPolicy` type + zod schema
+ * - the versioned storage-key codec (`accessPolicyStorageKey`)
+ * - `MessageActivation` (the `activation` fact on a received message)
+ * - the reserved owner-claim command constant + parser (`/dsh-claim`)
+ *
+ * It does NOT implement policy persistence orchestration, the authorization
+ * decision, Owner Claim session lifecycle, platform identity parsing, or any
+ * Web concerns. Those live in channel-control / channel-harness / channel-web,
+ * all of which share ONLY this contract.
+ *
+ * Policy model:
+ *   - Groups support disabled, named allowlist, or global access through an
+ *     explicit `defaultGroupRule`.
+ *   - `allowFrom: []` means DENY ALL, never "open".
+ *   - `requireMention` is an ACTIVATION fact, not authorization, and only
+ *     applies in group conversations.
+ */
+import { z } from 'zod';
+import type { MessageId } from './account.js';
+import type { MessagePart } from './messages.js';
+/** User-facing preset label. Runtime enforcement never branches on it. */
+export type AccessPreset = 'owner-only' | 'allowlist' | 'custom';
+export type DirectMessagePolicy = 'disabled' | 'allowlist' | 'open';
+export type GroupPolicy = 'disabled' | 'allowlist' | 'open';
+/**
+ * Within an already explicitly-allowed group:
+ *  - `allowlist`: `sender.id` must be present in `rule.allowFrom`
+ *  - `open`:      any sender in this NAMED group is authorized
+ */
+export type GroupSenderPolicy = 'allowlist' | 'open';
+export interface GroupAccessRule {
+    enabled: boolean;
+    senderPolicy: GroupSenderPolicy;
+    /** canonical sender.id exact-match allowlist. */
+    allowFrom: string[];
+    /**
+     * Only configurable to `true` when `descriptor.mentions === true`.
+     * `undefined !== true`, so a channel without reliable activation facts
+     * can never be required to mention (no fail-open).
+     */
+    requireMention: boolean;
+}
+export interface ChannelAccessPolicy {
+    /**
+     * Persistent schema version. Future semantic changes bump this version
+     * instead of silently re-interpreting old JSON. Unknown versions are
+     * treated as invalid (fail closed).
+     */
+    version: 1;
+    /**
+     * Web UX / materialization source only. Runtime enforcement must NOT branch
+     * on preset.
+     */
+    preset: AccessPreset;
+    /** The local operator's canonical sender.id (optional until claimed). */
+    ownerId?: string;
+    /** Private-chat rule. */
+    dmPolicy: DirectMessagePolicy;
+    /** DM canonical sender.id allowlist (V1 only exists for dmPolicy=allowlist). */
+    allowFrom: string[];
+    /** Whether groups are disabled, explicitly named, or governed by a default rule. */
+    groupPolicy: GroupPolicy;
+    /** canonical conversation.id -> rule. */
+    groups: Record<string, GroupAccessRule>;
+    /** Required only when groupPolicy=open; applies to every inbound group. */
+    defaultGroupRule?: GroupAccessRule;
+}
+export declare const accessPresetSchema: z.ZodEnum<{
+    "owner-only": "owner-only";
+    allowlist: "allowlist";
+    custom: "custom";
+}>;
+export declare const directMessagePolicySchema: z.ZodEnum<{
+    allowlist: "allowlist";
+    disabled: "disabled";
+    open: "open";
+}>;
+export declare const groupPolicySchema: z.ZodEnum<{
+    allowlist: "allowlist";
+    disabled: "disabled";
+    open: "open";
+}>;
+export declare const groupSenderPolicySchema: z.ZodEnum<{
+    allowlist: "allowlist";
+    open: "open";
+}>;
+export declare const groupAccessRuleSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    senderPolicy: z.ZodEnum<{
+        allowlist: "allowlist";
+        open: "open";
+    }>;
+    allowFrom: z.ZodArray<z.ZodString>;
+    requireMention: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * Strict access-policy schema. Matches the persisted `access:policy:v1:*` JSON.
+ * Every field is enforced; unknown keys are rejected (a policy JSON must be
+ * exactly what we understand). `ownerId` is optional (pre-claim).
+ */
+export declare const channelAccessPolicySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    preset: z.ZodEnum<{
+        "owner-only": "owner-only";
+        allowlist: "allowlist";
+        custom: "custom";
+    }>;
+    ownerId: z.ZodOptional<z.ZodString>;
+    dmPolicy: z.ZodEnum<{
+        allowlist: "allowlist";
+        disabled: "disabled";
+        open: "open";
+    }>;
+    allowFrom: z.ZodArray<z.ZodString>;
+    groupPolicy: z.ZodEnum<{
+        allowlist: "allowlist";
+        disabled: "disabled";
+        open: "open";
+    }>;
+    groups: z.ZodRecord<z.ZodString, z.ZodObject<{
+        enabled: z.ZodBoolean;
+        senderPolicy: z.ZodEnum<{
+            allowlist: "allowlist";
+            open: "open";
+        }>;
+        allowFrom: z.ZodArray<z.ZodString>;
+        requireMention: z.ZodBoolean;
+    }, z.core.$strip>>;
+    defaultGroupRule: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        senderPolicy: z.ZodEnum<{
+            allowlist: "allowlist";
+            open: "open";
+        }>;
+        allowFrom: z.ZodArray<z.ZodString>;
+        requireMention: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+/**
+ * Shared channel-domain KV namespace for an access policy. Reused by both the
+ * channel-control writer and the channel-harness reader so neither hard-codes
+ * the other's key format. E.g. `access:policy:v1:telegram:main`.
+ */
+export declare function accessPolicyStorageKey(channelId: string, accountId: string): string;
+/**
+ * The single reserved control-plane command. It is the ONLY inbound message
+ * that may be observed by the Control Plane before any access policy exists,
+ * and it MUST never reach the model / command dispatcher / Session / Binding.
+ *
+ * Format: `/dsh-claim <challengeCode>`
+ */
+export declare const OWNER_CLAIM_COMMAND = "/dsh-claim";
+export interface ParsedOwnerClaimCommand {
+    command: '/dsh-claim';
+    /** 8+ character one-time challenge code sent to the bot in a DM. */
+    code?: string;
+}
+/**
+ * True when `text` looks like the reserved claim command (exact slash at byte
+ * zero — shared with the official parseCommand convention). Both the Harness
+ * reserved-claim gate and the Control owner-claim observer use this same rule.
+ */
+export declare function isReservedClaimCommand(text: string): boolean;
+/**
+ * Parse a `/dsh-claim ...` line into its challenge code, or `undefined` when
+ * the text is not a claim command. Only the first whitespace-delimited token
+ * after the command is treated as the code; the rest is ignored.
+ */
+export declare function parseOwnerClaimCommand(text: string): ParsedOwnerClaimCommand | undefined;
+export interface MessageActivation {
+    /**
+     * Whether this message reliably, explicitly mentions the current Bot.
+     * `undefined`/`false` means we have no reliable fact — a rule requiring
+     * mention must NOT be treated as activated.
+     */
+    mentionedBot?: boolean;
+    /** Reserved for a future activation policy; V1 does not use it. */
+    repliedToBot?: boolean;
+}
+export interface AccessMessageRef {
+    id: MessageId;
+    content: MessagePart[];
+    replyTo?: MessageId;
+    createdAt?: number;
+    activation?: MessageActivation;
+}
+export type { MessageId };
+//# sourceMappingURL=access.d.ts.map

package/lib/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAMjD,0EAA0E;AAC1E,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEjE,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAEpE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,iBAAiB,CAAC;IAChC,iDAAiD;IACjD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,EAAE,CAAC,CAAC;IACX;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,gFAAgF;IAChF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,oFAAoF;IACpF,WAAW,EAAE,WAAW,CAAC;IACzB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,eAAe,CAAC;CACpC;AAaD,eAAO,MAAM,kBAAkB;;;;EAAgD,CAAC;AAChF,eAAO,MAAM,yBAAyB;;;;EAA4C,CAAC;AACnF,eAAO,MAAM,iBAAiB;;;;EAA4C,CAAC;AAC3E,eAAO,MAAM,uBAAuB;;;EAAgC,CAAC;AAErE,eAAO,MAAM,qBAAqB;;;;;;;;iBAKhC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA0BlC,CAAC;AAML;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnF;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,YAAY,CAAC;IACtB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI5D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAKxF;AAMD,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,SAAS,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/lib/access.js

@@ -0,0 +1,122 @@
+/**
+ * Channel Access Policy — the shared, versioned, cross-package contract for
+ * inbound access control.
+ *
+ * This module defines ONLY stable cross-package semantics:
+ *
+ * - the `ChannelAccessPolicy` type + zod schema
+ * - the versioned storage-key codec (`accessPolicyStorageKey`)
+ * - `MessageActivation` (the `activation` fact on a received message)
+ * - the reserved owner-claim command constant + parser (`/dsh-claim`)
+ *
+ * It does NOT implement policy persistence orchestration, the authorization
+ * decision, Owner Claim session lifecycle, platform identity parsing, or any
+ * Web concerns. Those live in channel-control / channel-harness / channel-web,
+ * all of which share ONLY this contract.
+ *
+ * Policy model:
+ *   - Groups support disabled, named allowlist, or global access through an
+ *     explicit `defaultGroupRule`.
+ *   - `allowFrom: []` means DENY ALL, never "open".
+ *   - `requireMention` is an ACTIVATION fact, not authorization, and only
+ *     applies in group conversations.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Zod schema (shared trust boundary — validation.ts / harness resolver reuse it)
+// ---------------------------------------------------------------------------
+const idSchema = z
+    .string()
+    .min(1)
+    // Trim leading/trailing whitespace is the ONLY allowed normalization. No
+    // lowercase, no fuzzy matching, no username resolution. IDs are opaque.
+    .trim();
+export const accessPresetSchema = z.enum(['owner-only', 'allowlist', 'custom']);
+export const directMessagePolicySchema = z.enum(['disabled', 'allowlist', 'open']);
+export const groupPolicySchema = z.enum(['disabled', 'allowlist', 'open']);
+export const groupSenderPolicySchema = z.enum(['allowlist', 'open']);
+export const groupAccessRuleSchema = z.object({
+    enabled: z.boolean(),
+    senderPolicy: groupSenderPolicySchema,
+    allowFrom: z.array(idSchema),
+    requireMention: z.boolean(),
+});
+/**
+ * Strict access-policy schema. Matches the persisted `access:policy:v1:*` JSON.
+ * Every field is enforced; unknown keys are rejected (a policy JSON must be
+ * exactly what we understand). `ownerId` is optional (pre-claim).
+ */
+export const channelAccessPolicySchema = z
+    .object({
+    version: z.literal(1),
+    preset: accessPresetSchema,
+    ownerId: idSchema.optional(),
+    dmPolicy: directMessagePolicySchema,
+    allowFrom: z.array(idSchema),
+    groupPolicy: groupPolicySchema,
+    groups: z.record(z.string().trim(), groupAccessRuleSchema),
+    defaultGroupRule: groupAccessRuleSchema.optional(),
+})
+    .strict()
+    .superRefine((policy, ctx) => {
+    if (policy.groupPolicy === 'open') {
+        if (!policy.defaultGroupRule) {
+            ctx.addIssue({ code: 'custom', path: ['defaultGroupRule'], message: 'required when groupPolicy is open' });
+        }
+        if (Object.keys(policy.groups).length > 0) {
+            ctx.addIssue({ code: 'custom', path: ['groups'], message: 'must be empty when groupPolicy is open' });
+        }
+        if (policy.defaultGroupRule?.enabled !== true) {
+            ctx.addIssue({ code: 'custom', path: ['defaultGroupRule', 'enabled'], message: 'must be enabled when groupPolicy is open' });
+        }
+    }
+    else if (policy.defaultGroupRule) {
+        ctx.addIssue({ code: 'custom', path: ['defaultGroupRule'], message: 'only allowed when groupPolicy is open' });
+    }
+});
+// ---------------------------------------------------------------------------
+// Storage key codec
+// ---------------------------------------------------------------------------
+/**
+ * Shared channel-domain KV namespace for an access policy. Reused by both the
+ * channel-control writer and the channel-harness reader so neither hard-codes
+ * the other's key format. E.g. `access:policy:v1:telegram:main`.
+ */
+export function accessPolicyStorageKey(channelId, accountId) {
+    return `access:policy:v1:${encodeURIComponent(channelId)}:${encodeURIComponent(accountId)}`;
+}
+// ---------------------------------------------------------------------------
+// Reserved owner-claim command
+// ---------------------------------------------------------------------------
+/**
+ * The single reserved control-plane command. It is the ONLY inbound message
+ * that may be observed by the Control Plane before any access policy exists,
+ * and it MUST never reach the model / command dispatcher / Session / Binding.
+ *
+ * Format: `/dsh-claim <challengeCode>`
+ */
+export const OWNER_CLAIM_COMMAND = '/dsh-claim';
+/**
+ * True when `text` looks like the reserved claim command (exact slash at byte
+ * zero — shared with the official parseCommand convention). Both the Harness
+ * reserved-claim gate and the Control owner-claim observer use this same rule.
+ */
+export function isReservedClaimCommand(text) {
+    if (!text.startsWith(OWNER_CLAIM_COMMAND))
+        return false;
+    const rest = text.slice(OWNER_CLAIM_COMMAND.length);
+    return rest.length === 0 || /^\s/.test(rest);
+}
+/**
+ * Parse a `/dsh-claim ...` line into its challenge code, or `undefined` when
+ * the text is not a claim command. Only the first whitespace-delimited token
+ * after the command is treated as the code; the rest is ignored.
+ */
+export function parseOwnerClaimCommand(text) {
+    if (!isReservedClaimCommand(text))
+        return undefined;
+    const rest = text.slice(OWNER_CLAIM_COMMAND.length).trim();
+    const code = rest.split(/\s+/)[0];
+    return { command: '/dsh-claim', code: code || undefined };
+}
+//# sourceMappingURL=access.js.map

package/lib/access.js.map

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

package/lib/account.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Identity types shared by every channel.
+ *
+ * All identities are branded strings so that a `ConversationId` cannot be
+ * silently passed where a `MessageId` is expected. Adapters are responsible
+ * for mapping platform-native ids into these types.
+ */
+/** Channel id, e.g. `'weixin'`, `'qq'`, `'dingtalk'`, `'lark'`. */
+export type ChannelId = string & {
+    readonly __brand: 'ChannelId';
+};
+/** Account id within a channel, e.g. `'main'`, `'bot01'`, `'corpA'`. */
+export type AccountId = string & {
+    readonly __brand: 'AccountId';
+};
+/** Conversation id within a channel account. */
+export type ConversationId = string & {
+    readonly __brand: 'ConversationId';
+};
+/** Optional thread id within a conversation. */
+export type ThreadId = string & {
+    readonly __brand: 'ThreadId';
+};
+/** Platform message id, used for dedup and reply correlation. */
+export type MessageId = string & {
+    readonly __brand: 'MessageId';
+};
+/** Platform sender id. */
+export type SenderId = string & {
+    readonly __brand: 'SenderId';
+};
+/** Key identifying one conversation binding target. */
+export interface ChannelConversationKey {
+    channelId: ChannelId;
+    accountId: AccountId;
+    conversationId: ConversationId;
+    threadId?: ThreadId;
+}
+/**
+ * Canonical string form of a conversation key:
+ * `channel:account:conversation[:thread]`.
+ *
+ * Never allowed to collapse a whole account into one session — each
+ * conversation (and optionally thread) is a distinct key.
+ */
+export declare function conversationKey(key: ChannelConversationKey): string;
+//# sourceMappingURL=account.d.ts.map

package/lib/account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,mEAAmE;AACnE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnE,wEAAwE;AACxE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnE,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAE7E,gDAAgD;AAChD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;AAEjE,iEAAiE;AACjE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnE,0BAA0B;AAC1B,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;AAEjE,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,sBAAsB,GAAG,MAAM,CAInE"}

package/lib/account.js

@@ -0,0 +1,20 @@
+/**
+ * Identity types shared by every channel.
+ *
+ * All identities are branded strings so that a `ConversationId` cannot be
+ * silently passed where a `MessageId` is expected. Adapters are responsible
+ * for mapping platform-native ids into these types.
+ */
+/**
+ * Canonical string form of a conversation key:
+ * `channel:account:conversation[:thread]`.
+ *
+ * Never allowed to collapse a whole account into one session — each
+ * conversation (and optionally thread) is a distinct key.
+ */
+export function conversationKey(key) {
+    return key.threadId
+        ? `${key.channelId}:${key.accountId}:${key.conversationId}:${key.threadId}`
+        : `${key.channelId}:${key.accountId}:${key.conversationId}`;
+}
+//# sourceMappingURL=account.js.map

package/lib/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4BH;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAA2B;IACzD,OAAO,GAAG,CAAC,QAAQ;QACjB,CAAC,CAAC,GAAG,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,QAAQ,EAAE;QAC3E,CAAC,CAAC,GAAG,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;AAChE,CAAC"}

package/lib/adapter.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `ChannelAdapter` contract: the stable boundary between a messaging
+ * platform and the Channel Core.
+ *
+ * An adapter maps platform semantics to the Channel Contract and delegates
+ * all SDK/package/protocol interaction to an upstream driver. Adapters never
+ * call Harness Agent APIs.
+ *
+ * Streaming may be target-aware: an adapter's *streaming capability* can be
+ * static (`capabilities.streaming`) or depend on the concrete reply target via
+ * the optional `resolveStreamingMode(target)` hook (e.g. QQ streams natively
+ * for C2C with a triggering message id, buffering for groups — but the fields
+ * are generic and reused by Telegram reply, Slack thread reply, Lark reply and
+ * DingTalk reference).
+ */
+import type { ChannelAdapterContext } from './context.js';
+import type { ChannelCapabilities, StreamingMode } from './capabilities.js';
+import type { AuthState } from './events.js';
+import type { ChannelConversationKey, MessageId } from './account.js';
+import type { OutboundMessage, SendResult } from './messages.js';
+import type { ChannelHealth } from './health.js';
+export interface ChannelTarget extends ChannelConversationKey {
+    /**
+     * Conversation kind of the reply target. Generic capability field — reused
+     * by replies whose semantics differ between DMs and groups (e.g. QQ: C2C
+     * native streaming vs. group buffered). Not QQ-specific.
+     */
+    conversationType?: 'dm' | 'group';
+    /**
+     * Id of the inbound message this reply answers. Lets adapters correlate a
+     * reply to the triggering message (Telegram reply, Slack thread reply, Lark
+     * reply, DingTalk reference, QQ C2C native streaming all reuse it). Not
+     * QQ-specific.
+     */
+    replyToMessageId?: MessageId;
+    /** Raw target data the adapter needs but core does not model. */
+    raw?: unknown;
+    /**
+     * Turn-scoped correlation id shared by every send within one Harness turn.
+     * Generic: adapters that correlate outbound sends to a single turn (e.g.
+     * Weixin run_id) read it; others ignore it.
+     */
+    runId?: string;
+}
+export interface CreateReplyOptions {
+    /** Send an initial "working on it" message immediately. */
+    placeholder?: string;
+    /** Whether reply content may contain markdown. */
+    markdown?: boolean;
+}
+export interface ReplyHandle {
+    /** Append a delta to the streaming reply. */
+    append(delta: string): Promise<void>;
+    /** Replace the whole reply content. */
+    replace(message: OutboundMessage): Promise<void>;
+    /** Finalize the reply, optionally with a final message. */
+    finish(message?: OutboundMessage): Promise<void>;
+    /** Mark the reply as failed. */
+    fail(error: unknown): Promise<void>;
+}
+export interface AuthChallenge {
+    /** Stable id of this challenge. */
+    id: string;
+    /** Human-readable instruction for the operator. */
+    instruction: string;
+    /** Optional QR/login URL for terminal or card rendering. */
+    qrUrl?: string;
+    /** Optional expiry timestamp. */
+    expiresAt?: number;
+    /** Adapter-specific payload; never a credential. */
+    payload?: unknown;
+}
+export interface AuthStatePoll {
+    state: Exclude<AuthState, 'unknown'>;
+    detail?: string;
+}
+export interface AuthInput {
+    kind: 'verification-code';
+    value: string;
+}
+export interface ChannelAdapter {
+    readonly id: string;
+    readonly capabilities: ChannelCapabilities;
+    /**
+     * Resolve the streaming mode for one reply target. Adapters whose
+     * streaming capability depends on the target (e.g. QQ: C2C + msgId →
+     * native, group → buffered) override the static `capabilities.streaming`.
+     * Defaults to `capabilities.streaming` when absent.
+     */
+    resolveStreamingMode?(target: ChannelTarget): StreamingMode;
+    start(ctx: ChannelAdapterContext): Promise<void>;
+    stop(): Promise<void>;
+    send(target: ChannelTarget, message: OutboundMessage): Promise<SendResult>;
+    /**
+     * Optional in-place edit of an already-sent message (e.g. Telegram
+     * `editMessageText` / `editMessageReplyMarkup`, Lark/DingTalk card update).
+     * Enables interactive flows that rewrite a single sent message (multi-select
+     * toggling, removing stale buttons). Adapters without an edit primitive leave
+     * it undefined; the harness must degrade those flows to a non-edit strategy.
+     */
+    edit?(target: ChannelTarget, messageId: string, message: OutboundMessage): Promise<SendResult>;
+    /**
+     * Best-effort typing indicator. Optional: adapters with a typing API (e.g.
+     * Weixin sendtyping) implement these; the harness fires them around turn
+     * start/end and NEVER lets a failure break reply delivery.
+     */
+    startTyping?(conversationId: string): Promise<void>;
+    stopTyping?(conversationId: string): Promise<void>;
+    startTypingForTarget?(target: ChannelTarget): Promise<void>;
+    stopTypingForTarget?(target: ChannelTarget): Promise<void>;
+    createReply?(target: ChannelTarget, options?: CreateReplyOptions): Promise<ReplyHandle>;
+    beginAuth?(): Promise<AuthChallenge>;
+    pollAuth?(challenge: AuthChallenge): Promise<AuthStatePoll>;
+    submitAuthInput?(challenge: AuthChallenge, input: AuthInput): Promise<void> | void;
+    getHealth?(): Promise<ChannelHealth>;
+}
+/** Emit a message event through the adapter context helper. */
+export declare function isChannelAdapter(value: unknown): value is ChannelAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/lib/adapter.d.ts.map

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

package/lib/adapter.js

@@ -0,0 +1,6 @@
+import { channelAdapterShapeSchema } from './schema.js';
+/** Emit a message event through the adapter context helper. */
+export function isChannelAdapter(value) {
+    return channelAdapterShapeSchema.safeParse(value).success;
+}
+//# sourceMappingURL=adapter.js.map