@kl-c/matrixos 0.1.40 → 0.2.0

package/dist/budget/agent-budget.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Per-agent token budget (cost guardrails).
+ *
+ * Tracks cumulative tokens consumed per agent and triggers an action when
+ * the configured budget is exceeded. Inspired by Sprint B9 (cost-alerter)
+ * but per-agent instead of global.
+ *
+ * Defaults: tank=50k, morpheus=200k, general=100k, unlimited for others.
+ * Action on overrun: warn (log) by default; can be set to "throttle" (block
+ * the call) or "throw" (reject the call) via the action field.
+ */
+export type BudgetAction = "warn" | "throttle" | "throw";
+export type BudgetConfig = {
+    tokens: number;
+    action: BudgetAction;
+};
+export declare function setBudget(agent: string, config: BudgetConfig): void;
+export declare function recordTokens(agent: string, tokens: number): BudgetStatus;
+export declare function getUsed(agent: string): number;
+export declare function resetBudget(agent?: string): void;
+export type BudgetStatus = {
+    used: number;
+    limit: number;
+    percent: number;
+    action: BudgetAction | null;
+    over: boolean;
+};
+/** Convenience: throw if action=throw and budget is over. Returns the status either way. */
+export declare function enforceBudget(agent: string, tokens: number): BudgetStatus;

package/dist/cli/adopt.d.ts

@@ -0,0 +1,42 @@
+/**
+ * matrixos adopt [telegram]
+ *
+ * Interactive adoption flow: asks the user for credentials, ingests them
+ * via the same .klc-gateway.env file used by `gateway set-token`, and
+ * validates the token against the platform API.
+ *
+ * Why a dedicated command and not just `gateway set-token`:
+ * - `set-token` is the low-level "write one token" primitive
+ * - `adopt` is the high-level "configure a channel end-to-end" UX
+ *   (token + chat id + optional validation)
+ * - `adopt` is what a user re-runs when they want to fix or migrate
+ *   their setup
+ *
+ * The slash command `/adopt` in Telegram dispatches to this same flow
+ * (see gateway-handler.ts).
+ *
+ * Token is NEVER hardcoded. Always prompted (masked) or read from --token.
+ */
+export interface AdoptOptions {
+    readonly channel?: "telegram";
+    readonly envPath?: string;
+    readonly token?: string;
+    readonly allowedChatId?: string;
+    readonly nonInteractive?: boolean;
+    /** Mock the validator (for tests). Returns true if the token is valid. */
+    readonly validate?: (token: string) => Promise<boolean>;
+}
+export interface AdoptResult {
+    readonly ok: boolean;
+    readonly channel: string;
+    readonly tokenWritten: boolean;
+    readonly allowedChatId?: string;
+    readonly validated: boolean;
+    readonly message: string;
+    /** Never the actual token — only a boolean and a length. */
+    readonly tokenLength?: number;
+}
+export declare function upsertEnvFile(path: string, updates: Record<string, string>): void;
+/** Default Telegram validator: hits getMe. Returns true on 200. */
+export declare function defaultTelegramValidate(token: string): Promise<boolean>;
+export declare function runAdopt(opts?: AdoptOptions): Promise<AdoptResult>;

package/dist/cli/gateway-start.d.ts

@@ -0,0 +1,39 @@
+/**
+ * matrixos gateway start [telegram]
+ *
+ * Boots the MaTrixOS gateway: loads `.klc-gateway.env`, builds a
+ * GatewayConfig, instantiates the requested channel adapter, registers it
+ * with the MatrixGateway, sets a message handler that shells out to
+ * `matrixos run`, and starts long-polling.
+ *
+ * Token handling: the token is read from `.klc-gateway.env` (chmod 600)
+ * via `loadGatewayEnv()`. NEVER hardcoded. Set it with
+ * `matrixos gateway set-token telegram --token "<token>"` or
+ * `matrixos gateway set-token telegram -i` (masked interactive prompt).
+ *
+ * The file `.klc-gateway.env` is gitignored (created by `set-token`).
+ */
+import { MatrixGateway, TelegramAdapter, type GatewayConfig, type TelegramChannelConfig } from "@matrixos/matrix-gateway-core";
+export interface GatewayStartOptions {
+    readonly channel?: "telegram" | "discord";
+    readonly envPath?: string;
+    readonly command?: string;
+    readonly args?: string[];
+    readonly timeoutMs?: number;
+    /** Mock-friendly: inject a built gateway instead of constructing one. */
+    readonly gatewayFactory?: (config: GatewayConfig) => MatrixGateway;
+    readonly adapterFactory?: (config: TelegramChannelConfig) => TelegramAdapter;
+}
+export interface GatewayStartResult {
+    readonly ok: boolean;
+    readonly channel: string;
+    readonly pid: number;
+    readonly envLoaded: boolean;
+    readonly tokenPresent: boolean;
+    readonly message: string;
+}
+/** Parse a .klc-gateway.env file (KEY=value, no shell quoting) without dotenv dep. */
+export declare function loadGatewayEnv(path?: string): Record<string, string>;
+export declare function buildTelegramConfig(env: Record<string, string>): TelegramChannelConfig;
+export declare function buildGatewayConfig(channel: TelegramChannelConfig): GatewayConfig;
+export declare function runGatewayStart(opts?: GatewayStartOptions): Promise<GatewayStartResult>;