@cjhyy/code-shell-pet 0.8.0

package/dist/gateway.js

@@ -0,0 +1,263 @@
+import { hasOnlyDeclaredToolArguments } from "./tool-arguments.js";
+export const GATEWAY_TOOL_NAME = "Gateway";
+export const gatewayToolDef = {
+    name: GATEWAY_TOOL_NAME,
+    description: "First-level, read-only progressive discovery for Chat Gateway. Search only the channels " +
+        "granted to this turn, or describe the exact inbound/outbound contract of one channel. " +
+        "Use GatewayReply as the second-level execution tool for the current originating conversation.",
+    inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            action: {
+                type: "string",
+                enum: ["search", "describe"],
+                description: "search returns compact channel matches; describe returns one exact channel contract.",
+            },
+            query: {
+                type: "string",
+                minLength: 1,
+                maxLength: 128,
+                description: "Optional search terms. Omit to list every granted channel. Use terms such as " +
+                    "channel:telegram, inbound:file, outbound:image, outbound:proactive, " +
+                    "outbound:direct, button:native, or current.",
+            },
+            channel: {
+                type: "string",
+                minLength: 1,
+                maxLength: 32,
+                description: "Granted channel name for describe. Omit it to inspect the current originating channel.",
+            },
+        },
+        required: ["action"],
+    },
+};
+export function gatewayAvailability(ctx) {
+    return Boolean(ctx.profileMeta?.petGateway);
+}
+export async function gatewayTool(args, ctx) {
+    const catalog = ctx?.runScopedServices
+        ?.petGateway;
+    if (!catalog)
+        return "Error: Gateway is available only in a Mimi turn with Gateway context.";
+    if (!hasOnlyDeclaredToolArguments(args, ["action", "query", "channel"]) ||
+        typeof args.action !== "string") {
+        return "Error: Gateway requires an action and accepts only query or channel.";
+    }
+    if (args.action === "search") {
+        if (args.channel !== undefined) {
+            return "Error: Gateway search does not accept channel.";
+        }
+        if (args.query !== undefined &&
+            (typeof args.query !== "string" ||
+                args.query.length < 1 ||
+                args.query.length > 128 ||
+                args.query.trim().length < 1)) {
+            return "Error: Gateway search query must be 1 to 128 non-blank characters.";
+        }
+        const query = typeof args.query === "string" ? args.query : undefined;
+        return JSON.stringify({
+            currentChannel: catalog.currentChannel,
+            matches: catalog.channels
+                .filter((entry) => matchesGatewayQuery(entry, catalog.currentChannel, query))
+                .map(({ channel }) => ({
+                channel,
+                current: channel === catalog.currentChannel,
+            })),
+            next: `Call ${GATEWAY_TOOL_NAME} with action=describe and an optional matched channel, then use GatewayReply for the current route.`,
+        });
+    }
+    if (args.action !== "describe") {
+        return "Error: Gateway action must be search or describe.";
+    }
+    if (args.query !== undefined) {
+        return "Error: Gateway describe does not accept query.";
+    }
+    if (args.channel !== undefined &&
+        (typeof args.channel !== "string" || !isChannelName(args.channel))) {
+        return "Error: Gateway channel must be a configured channel name.";
+    }
+    const requested = typeof args.channel === "string" ? args.channel.toLowerCase() : catalog.currentChannel;
+    const selected = catalog.channels.find(({ channel }) => channel === requested);
+    if (!selected) {
+        return `Error: channel ${requested} is not granted to this Gateway turn. Call search first.`;
+    }
+    return JSON.stringify({
+        current: selected.channel === catalog.currentChannel,
+        channel: selected.channel,
+        capabilities: selected.capabilities,
+        execution: selected.channel === catalog.currentChannel
+            ? {
+                tool: "GatewayReply",
+                destination: "current originating IM conversation",
+            }
+            : {
+                tool: null,
+                reason: "GatewayReply is intentionally bound to the current originating conversation.",
+            },
+    });
+}
+function matchesGatewayQuery(entry, currentChannel, query) {
+    if (query === undefined)
+        return true;
+    const terms = query.toLowerCase().trim().split(/\s+/u);
+    return terms.every((term) => matchesGatewayTerm(entry, currentChannel, term));
+}
+function matchesGatewayTerm(entry, currentChannel, term) {
+    if (term === "current")
+        return entry.channel === currentChannel;
+    const [scope, value, extra] = term.split(":");
+    if (extra !== undefined || value === "")
+        return false;
+    if (value !== undefined) {
+        if (scope === "channel")
+            return entry.channel.includes(value);
+        if (scope === "button")
+            return entry.capabilities.outbound.button === value;
+        if (scope === "inbound") {
+            return (value === "text" || entry.capabilities.inbound.attachments.includes(asAttachment(value)));
+        }
+        if (scope === "outbound") {
+            return (value === "text" ||
+                (value === "proactive" && entry.capabilities.outbound.proactive === true) ||
+                (value === "direct" && entry.capabilities.outbound.direct === true) ||
+                entry.capabilities.outbound.attachments.includes(asAttachment(value)));
+        }
+        return false;
+    }
+    if (entry.channel.includes(term))
+        return true;
+    if (entry.capabilities.outbound.button === term)
+        return true;
+    if (term === "text")
+        return true;
+    if (term === "proactive")
+        return entry.capabilities.outbound.proactive === true;
+    if (term === "direct")
+        return entry.capabilities.outbound.direct === true;
+    const attachment = asAttachment(term);
+    return (entry.capabilities.inbound.attachments.includes(attachment) ||
+        entry.capabilities.outbound.attachments.includes(attachment));
+}
+function asAttachment(value) {
+    return value;
+}
+export function parsePetGatewayCatalog(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ["currentChannel", "channels"]))
+        return undefined;
+    if (!isChannelName(value.currentChannel) || !Array.isArray(value.channels))
+        return undefined;
+    if (value.channels.length < 1 || value.channels.length > 32)
+        return undefined;
+    const channels = [];
+    const names = new Set();
+    for (const raw of value.channels) {
+        if (!isRecord(raw) || !hasExactKeys(raw, ["channel", "capabilities"]))
+            return undefined;
+        if (!isChannelName(raw.channel) || names.has(raw.channel))
+            return undefined;
+        const capabilities = parseCapabilities(raw.capabilities);
+        if (!capabilities)
+            return undefined;
+        names.add(raw.channel);
+        channels.push(Object.freeze({ channel: raw.channel, capabilities }));
+    }
+    if (!names.has(value.currentChannel))
+        return undefined;
+    return Object.freeze({
+        currentChannel: value.currentChannel,
+        channels: Object.freeze(channels),
+    });
+}
+function parseCapabilities(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ["inbound", "outbound"]))
+        return undefined;
+    if (!isRecord(value.inbound) ||
+        !hasExactKeys(value.inbound, ["text", "attachments"]) ||
+        value.inbound.text !== true) {
+        return undefined;
+    }
+    const inboundAttachments = parseAttachmentKinds(value.inbound.attachments);
+    if (!inboundAttachments || !isRecord(value.outbound) || value.outbound.text !== true) {
+        return undefined;
+    }
+    if (Object.keys(value.outbound).some((key) => ![
+        "text",
+        // `proactive` is part of the chat package's capability shape. It was
+        // missing from this allowlist, and the check rejects ANY unknown key —
+        // so every real channel failed catalog validation and Mimi silently
+        // lost Gateway discovery on IM turns.
+        "proactive",
+        "direct",
+        "maxTextLength",
+        "button",
+        "attachments",
+        "maxAttachments",
+        "maxAttachmentBytes",
+    ].includes(key)) ||
+        (value.outbound.button !== "native" && value.outbound.button !== "link")) {
+        return undefined;
+    }
+    const outboundAttachments = parseAttachmentKinds(value.outbound.attachments);
+    if (!outboundAttachments)
+        return undefined;
+    const maxTextLength = optionalBoundedInteger(value.outbound.maxTextLength, 1, 8_000);
+    const maxAttachments = optionalBoundedInteger(value.outbound.maxAttachments, 1, 4);
+    const maxAttachmentBytes = optionalBoundedInteger(value.outbound.maxAttachmentBytes, 1, 10 * 1024 * 1024);
+    if (maxTextLength === null || maxAttachments === null || maxAttachmentBytes === null) {
+        return undefined;
+    }
+    // Must be a real boolean when present: the value reaches Mimi's prompt as a
+    // capability claim, so a truthy string would misreport what the channel can do.
+    const proactive = value.outbound.proactive;
+    if (proactive !== undefined && typeof proactive !== "boolean")
+        return undefined;
+    const direct = value.outbound.direct;
+    if (direct !== undefined && typeof direct !== "boolean")
+        return undefined;
+    return Object.freeze({
+        inbound: Object.freeze({ text: true, attachments: inboundAttachments }),
+        outbound: Object.freeze({
+            text: true,
+            // Carried through rather than dropped — "can push unprompted" is exactly
+            // the kind of thing Mimi must not assume.
+            ...(proactive === undefined ? {} : { proactive }),
+            ...(direct === undefined ? {} : { direct }),
+            ...(maxTextLength === undefined ? {} : { maxTextLength }),
+            button: value.outbound.button,
+            attachments: outboundAttachments,
+            ...(maxAttachments === undefined ? {} : { maxAttachments }),
+            ...(maxAttachmentBytes === undefined ? {} : { maxAttachmentBytes }),
+        }),
+    });
+}
+function parseAttachmentKinds(value) {
+    if (!Array.isArray(value) ||
+        value.length > 4 ||
+        !value.every((kind) => ["image", "file", "audio", "video"].includes(String(kind))) ||
+        new Set(value).size !== value.length) {
+        return undefined;
+    }
+    return Object.freeze([...value]);
+}
+function optionalBoundedInteger(value, minimum, maximum) {
+    if (value === undefined)
+        return undefined;
+    return Number.isSafeInteger(value) && Number(value) >= minimum && Number(value) <= maximum
+        ? Number(value)
+        : null;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function hasExactKeys(record, expected) {
+    const actual = Object.keys(record).sort();
+    const sorted = [...expected].sort();
+    return actual.length === sorted.length && actual.every((key, index) => key === sorted[index]);
+}
+function isChannelName(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 32 &&
+        /^[a-z0-9][a-z0-9_-]*$/u.test(value));
+}

package/dist/host-actions.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Generic "host action" envelope: a Mimi tool records a validated structured
+ * request during her turn, and the host executes it only after the turn ends,
+ * folding the real outcome back into the reply. One convention shared by every
+ * atomic CodeShell capability exposed to Mimi (mobile remote, long-task
+ * control, memory, ...), so adding a capability means one tool + one host
+ * executor instead of a bespoke wire per feature.
+ */
+import type { ToolContext, ToolDefinition, ToolVisibilityContext } from "@cjhyy/code-shell-core/extension";
+export declare const PET_HOST_ACTION_KINDS: readonly ["mobileRemote", "longTaskControl", "memory", "gatewayReply", "followUpMutation", "sessionArchive", "outboundMessage"];
+export type PetHostActionKind = (typeof PET_HOST_ACTION_KINDS)[number];
+export declare function isPetHostActionKind(value: unknown): value is PetHostActionKind;
+export interface PetHostActionRequest {
+    kind: PetHostActionKind;
+    payload: Record<string, unknown>;
+}
+export interface PetHostActionDecision {
+    ok: boolean;
+    error?: string;
+}
+export type PetHostActionService = (request: PetHostActionRequest) => PetHostActionDecision;
+export type PetGatewayReplyAttachmentKind = "image" | "file" | "audio" | "video";
+/** Trusted per-route limits used to rewrite and execute the GatewayReply tool. */
+export interface PetGatewayReplyCapability {
+    button: "native" | "link";
+    attachments: readonly PetGatewayReplyAttachmentKind[];
+    maxTextLength: number;
+    maxAttachments: number;
+    maxAttachmentBytes: number;
+}
+/**
+ * Validate the full worker-to-host envelope, including each kind's payload.
+ * Tool input schemas are not a trust boundary: the worker response still
+ * crosses a process boundary and must fail closed before a host side effect.
+ */
+export declare function isPetHostActionRequest(value: unknown): value is PetHostActionRequest;
+export declare function hostActionAvailability(kind: PetHostActionKind): (ctx: ToolVisibilityContext) => boolean;
+export declare function hostActionService(ctx?: ToolContext): PetHostActionService | undefined;
+export declare const GATEWAY_REPLY_TOOL_NAME = "GatewayReply";
+export declare const gatewayReplyToolDef: ToolDefinition;
+export declare const gatewayReplyAvailability: (ctx: ToolVisibilityContext) => boolean;
+export declare function rewriteGatewayReplyDef(def: ToolDefinition, ctx: ToolVisibilityContext): ToolDefinition;
+export declare function gatewayReplyTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const CONTROL_LONG_TASK_TOOL_NAME = "ControlLongTask";
+export declare const controlLongTaskToolDef: ToolDefinition;
+export declare const controlLongTaskAvailability: (ctx: ToolVisibilityContext) => boolean;
+export declare function controlLongTaskTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const MEMORY_TOOL_NAME = "Memory";
+export declare const memoryToolDef: ToolDefinition;
+export declare const memoryAvailability: (ctx: ToolVisibilityContext) => boolean;
+export declare function memoryTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;