@primusclaw/personal-agent-runtime 0.0.0-stage → 0.1.0

package/dist/types/crypto/node-crypto.d.ts

@@ -0,0 +1,2 @@
+import type { Crypto } from "@primusclaw/personal-agent";
+export declare const nodeCrypto: Crypto;

package/dist/types/crypto/py-base64.d.ts

@@ -0,0 +1,8 @@
+/** The data was not base64 Python would read (`binascii.Error`). */
+export declare class Base64Error extends Error {
+    readonly name = "Base64Error";
+}
+/** Python's `base64.urlsafe_b64decode` (binascii non-strict mode). */
+export declare function urlsafeB64Decode(input: string | Uint8Array): Uint8Array;
+/** Python's `base64.urlsafe_b64encode`: padded, `-_` alphabet. */
+export declare function urlsafeB64Encode(data: Uint8Array): string;

package/dist/types/crypto-random.d.ts

@@ -0,0 +1,3 @@
+import type { Random } from "@primusclaw/personal-agent";
+/** Randomness from the operating system's CSPRNG (`node:crypto`). */
+export declare const cryptoRandom: Random;

package/dist/types/exchange/index.d.ts

@@ -0,0 +1,2 @@
+/** The identity service's token exchange and binding requests (exchange.py), as core's TokenExchange plugin. */
+export * from "./token-exchange.js";

package/dist/types/exchange/serial.d.ts

@@ -0,0 +1,8 @@
+/**
+ * One task at a time per key, in the order they asked (an asyncio.Lock per key): a later task runs once the earlier
+ * one has finished, whatever its outcome, and sees what it left behind.
+ */
+export declare class PerKeySerial {
+    private readonly tails;
+    run<T>(key: string, task: () => Promise<T>): Promise<T>;
+}

package/dist/types/exchange/token-exchange.d.ts

@@ -0,0 +1,56 @@
+import { type BindingRequest, type Clock, type ExchangeError, type ExchangeFailed, type ExchangeSettings, type ExchangeUnavailable, type Result, type TokenExchange } from "@primusclaw/personal-agent";
+export declare const GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+export declare const USER_REF = "urn:primus:params:oauth:token-type:user-ref";
+export declare const ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token";
+/** A token with less than this left is never handed out. */
+export declare const REFRESH_MARGIN_SECONDS = 60;
+/** How long "not bound" is remembered, so chatter does not hammer the identity service. */
+export declare const NOT_BOUND_TTL_SECONDS = 15;
+/** A confirm link with less than this left is not handed out again. */
+export declare const REQUEST_MARGIN_SECONDS = 60;
+type Fetch = typeof fetch;
+/** The JSON object of an answer ({} when it is not one). */
+/** How long an exchange or a binding request may take, answer included. */
+export declare const EXCHANGE_TIMEOUT_MS = 30000;
+/**
+ * Short-lived tokens from the identity service's OAuth 2.0 token exchange (RFC 8693). The worker is a service client:
+ * for a channel user with a confirmed binding (issuer + their user id) it trades its own client credentials for a token
+ * that acts as that person for about 10 minutes. Nothing long-lived is kept. A user with no binding gets `not_bound`
+ * (remembered briefly) and is offered a binding request: a one-time link they open, sign in at and confirm once.
+ */
+export declare class HttpTokenExchange implements TokenExchange {
+    private readonly settings;
+    private readonly clock;
+    private readonly fetchFn;
+    /** The whole call, answer included (the Python worker's HTTP client had 30 s). */
+    private readonly timeoutMs;
+    readonly enabled = true;
+    /** user -> (token, usable until) */
+    private readonly tokens;
+    /** user -> remembered until */
+    private readonly unbound;
+    /** user -> (open binding request, usable until) */
+    private readonly requests;
+    private readonly exchanges;
+    private readonly bindings;
+    private readonly authorization;
+    constructor(settings: ExchangeSettings, clock: Clock, fetchFn?: Fetch, 
+    /** The whole call, answer included (the Python worker's HTTP client had 30 s). */
+    timeoutMs?: number);
+    private now;
+    invalidate(userId: string): void;
+    private cachedToken;
+    /** A token acting as the person bound to `userId` (one exchange in flight per user). */
+    tokenFor(userId: string): Promise<Result<string, ExchangeError>>;
+    private exchange;
+    private cachedRequest;
+    /**
+     * The confirm link for `userId`. A newer request withdraws the older link at the identity service, so the one still
+     * open is handed out again. `email`, when the channel supplied one, restricts who can confirm it.
+     */
+    bindingRequest(userId: string, email?: string): Promise<Result<BindingRequest, ExchangeFailed | ExchangeUnavailable>>;
+    /** The binding endpoint: as configured, else beside the token endpoint (.../oauth/token -> .../oauth/binding-requests). */
+    bindingUrl(): string;
+    private requestBinding;
+}
+export {};

package/dist/types/github/api.d.ts

@@ -0,0 +1,44 @@
+export declare const GITHUB_API = "https://api.github.com";
+export declare const GITHUB_HEADERS: Readonly<Record<string, string>>;
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** GitHub refused, or could not be reached (status 0). `code` never carries a body or a secret. */
+export declare class GithubApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code?: string);
+}
+/** Where the token of an authenticated call comes from. */
+export interface GithubTokenSource {
+    token(): Promise<string>;
+    /** A token the server no longer accepts: the next `token()` mints or reads a new one. */
+    invalidate(): void;
+}
+export interface GithubRequest {
+    readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+    /** The path under the API root, starting with "/" (query included). */
+    readonly path: string;
+    readonly body?: unknown;
+    readonly timeoutMs?: number;
+}
+export interface GithubApiOptions {
+    readonly fetch?: FetchLike;
+    readonly apiUrl?: string;
+    /** None: calls are anonymous (public reads only). */
+    readonly tokens?: GithubTokenSource;
+    readonly timeoutMs?: number;
+}
+export declare class GithubApi {
+    readonly apiUrl: string;
+    private readonly fetchImpl;
+    private readonly tokens;
+    private readonly timeoutMs;
+    constructor(options?: GithubApiOptions);
+    /**
+     * One call. With a token source, a 401 invalidates the cached token and the call is made once more with a fresh one. A
+     * transport failure is GithubApiError(0, "transport_<name>"); any HTTP answer is returned to the caller to read.
+     */
+    request(request: GithubRequest): Promise<Response>;
+    private once;
+}
+/** A path segment as GitHub's URLs take it (`quote(x, safe='')`). */
+export declare function segment(value: string): string;

package/dist/types/github/app-token.d.ts

@@ -0,0 +1,46 @@
+import { type FetchLike, type GithubTokenSource } from "./api.js";
+/** No usable GitHub credential right now. `code` says why and never carries a secret. */
+export declare class GithubAuthError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/** The JWT a GitHub App signs to prove itself (valid 10 minutes at most; iat is back-dated for clock skew). */
+export declare function appJwt(appId: string, keyPem: string | Buffer, nowSeconds: number): string;
+export interface AppTokenOptions {
+    readonly appId: string;
+    readonly installationId: string;
+    /** The App's private key (PEM), read when a token is minted. */
+    readonly key: () => Promise<string | Buffer>;
+    /** The repository names (without owner) the minted token is limited to. */
+    readonly repositories: readonly string[];
+    /** The permissions the minted token is limited to, e.g. `{ issues: "write" }`. */
+    readonly permissions: Readonly<Record<string, string>>;
+    readonly fetch?: FetchLike;
+    readonly apiUrl?: string;
+    /** Seconds since the epoch. */
+    readonly clock?: () => number;
+}
+export declare class AppTokenSource implements GithubTokenSource {
+    private readonly options;
+    private cached;
+    private minting;
+    private readonly fetchImpl;
+    private readonly apiUrl;
+    private readonly clock;
+    constructor(options: AppTokenOptions);
+    invalidate(): void;
+    token(): Promise<string>;
+    private mint;
+}
+/** A plain token, read when it is used (a mounted file or a secret); an App token first, when there is one. */
+export declare class FallbackTokenSource implements GithubTokenSource {
+    private readonly app;
+    private readonly plain;
+    private readonly clock;
+    private readonly appRetrySeconds;
+    private readonly onAppFailure;
+    private appFailedAt;
+    constructor(app: GithubTokenSource | undefined, plain: (() => Promise<string>) | undefined, clock?: () => number, appRetrySeconds?: number, onAppFailure?: (code: string) => void);
+    invalidate(): void;
+    token(): Promise<string>;
+}

package/dist/types/github/credential-client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The identity service's `/oauth/external-credentials` calls, made as the worker's service client for a person it holds a
+ * binding for (the same client and the same `external:<issuer>|<directory id>` reference as the token exchange). A person
+ * with no binding is `not_bound`. Nothing of an answer is kept but its fields: a request that carries a token must not be
+ * able to put it in a log line.
+ */
+import { type CredentialFailure, type GithubCredentials, type GithubState, type Result } from "@primusclaw/personal-agent";
+import { z } from "zod";
+import type { FetchLike } from "./api.js";
+declare const answer: z.ZodObject<{
+    user_id: z.ZodOptional<z.ZodUnknown>;
+    item: z.ZodOptional<z.ZodUnknown>;
+    bound: z.ZodOptional<z.ZodUnknown>;
+    unbound: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+type Answer = z.infer<typeof answer>;
+export declare function stateOf(data: Answer): GithubState;
+export interface CredentialClientOptions {
+    readonly baseUrl: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly issuer: string;
+    readonly fetch?: FetchLike;
+}
+export declare class IdentityCredentialClient implements GithubCredentials {
+    private readonly options;
+    private readonly base;
+    private readonly fetchImpl;
+    constructor(options: CredentialClientOptions);
+    private call;
+    status(userId: string): Promise<Result<GithubState, CredentialFailure>>;
+    bind(userId: string, token: string): Promise<Result<GithubState, CredentialFailure>>;
+    unbind(userId: string): Promise<Result<boolean, CredentialFailure>>;
+    setDelegation(userId: string, enabled: boolean): Promise<Result<GithubState, CredentialFailure>>;
+}
+export {};

package/dist/types/github/device-flow.d.ts

@@ -0,0 +1,28 @@
+/**
+ * RFC 8628 against github.com with a public client (no secret); the scope asked for is always `repo`. Nothing GitHub
+ * answers is kept but the fields read: a failure is only its reason, never a body, a code or a token.
+ */
+import { type Clock, type DeviceCode, type DeviceFlow, type DeviceFlowCancelled, type DeviceFlowFailed, type Result } from "@primusclaw/personal-agent";
+import type { FetchLike } from "./api.js";
+export declare const DEVICE_CODE_URL = "https://github.com/login/device/code";
+export declare const ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token";
+export declare const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export declare const MAX_DEVICE_WAIT_SECONDS: number;
+export interface DeviceFlowOptions {
+    readonly clientId: string;
+    readonly clock: Clock;
+    readonly fetch?: FetchLike;
+}
+export declare class GithubDeviceFlow implements DeviceFlow {
+    private readonly options;
+    private readonly fetchImpl;
+    constructor(options: DeviceFlowOptions);
+    private post;
+    start(): Promise<Result<DeviceCode, DeviceFlowFailed>>;
+    /**
+     * Polls until the person approves: the token, or why not. Honours `interval` and `slow_down`; gives up when the code runs
+     * out (or after MAX_DEVICE_WAIT_SECONDS, whichever is first).
+     */
+    waitForToken(code: DeviceCode, signal?: AbortSignal): Promise<Result<string, DeviceFlowFailed | DeviceFlowCancelled>>;
+    private poll;
+}

package/dist/types/github/feedback-config.d.ts

@@ -0,0 +1,26 @@
+import { type FeedbackSink, type Logger } from "@primusclaw/personal-agent";
+import { type FetchLike } from "./api.js";
+export interface FeedbackConfig {
+    /** `owner/name` ("" when none). */
+    readonly repo: string;
+    readonly appId: string;
+    readonly installationId: string;
+    /** The App's private key (PEM) as a mounted file; "" when the key came from a secret store (`keyPem`). */
+    readonly keyFile: string;
+    /** The same key read from a secret store at start, held in memory only. */
+    readonly keyPem: string;
+    readonly tokenFile: string;
+    readonly apiUrl: string;
+}
+export declare function feedbackConfigFromEnv(env: Readonly<Record<string, string | undefined>>, keyPem?: string): FeedbackConfig;
+export declare function appConfigured(config: FeedbackConfig): boolean;
+/** A repository and some credential; whether the credential works is only known when it is used. */
+export declare function feedbackConfigured(config: FeedbackConfig): boolean;
+export interface FeedbackSinkOptions {
+    readonly fetch?: FetchLike;
+    /** Seconds since the epoch. */
+    readonly clock?: () => number;
+    readonly log: Logger;
+}
+/** The sink feedback delivers to, or undefined when nothing is configured (reports are then only recorded). */
+export declare function feedbackSink(config: FeedbackConfig, options: FeedbackSinkOptions): FeedbackSink | undefined;

package/dist/types/github/feedback-issues.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Feedback's issues in one GitHub repository (the Python worker's `feedback.GitHubIssues`): the FeedbackSink core
+ * delivers reports to. Every call goes through the shared GitHub client (`api.ts`: its headers, one retry with a fresh
+ * token on a 401); a failure is a status and a short code, never a body or a secret.
+ */
+import { type FeedbackSink, type IssueRef, type Logger, type Result, type SinkError } from "@primusclaw/personal-agent";
+import { GithubApi } from "./api.js";
+export declare const FEEDBACK_LABEL = "clawy-feedback";
+export declare class GithubIssueSink implements FeedbackSink {
+    private readonly api;
+    private readonly log;
+    private labelReady;
+    private readonly repoPath;
+    constructor(api: GithubApi, 
+    /** `owner/name`. */
+    repo: string, log: Logger);
+    createIssue(title: string, body: string, labels: readonly string[]): Promise<Result<IssueRef, SinkError>>;
+    findIssue(marker: string, sinceEpochMs: number): Promise<Result<IssueRef | undefined, SinkError>>;
+    hasComment(issue: number, marker: string, sinceEpochMs: number): Promise<Result<boolean, SinkError>>;
+    comment(issue: number, body: string): Promise<Result<void, SinkError>>;
+    /** The feedback label, made once if the repository lacks it. Best effort: a report is worth more than its label. */
+    private ensureLabel;
+}

package/dist/types/github/feedback-worker.d.ts

@@ -0,0 +1,11 @@
+import { type WorkerInfo } from "@primusclaw/personal-agent";
+/**
+ * The `version` of a package.json (the worker's own package: whoever assembles the worker passes its URL), "unknown"
+ * when the file cannot be read or names no version.
+ */
+export declare function packageVersion(packageJson: URL): string;
+/** The deployment as a report names it. */
+export declare function workerInfoFromEnv(env: Readonly<Record<string, string | undefined>>, worker: {
+    readonly pluginId: string;
+    readonly version: string;
+}): WorkerInfo;

package/dist/types/github/index.d.ts

@@ -0,0 +1,7 @@
+/** The GitHub adapters the worker's assembly injects into the review service (the ports in core's `ports/github.ts`). */
+export { GITHUB_API, GithubApi, GithubApiError, type GithubApiOptions, type GithubTokenSource } from "./api.js";
+export { AppTokenSource, FallbackTokenSource, GithubAuthError, appJwt, type AppTokenOptions } from "./app-token.js";
+export { IdentityCredentialClient, type CredentialClientOptions } from "./credential-client.js";
+export { GithubDeviceFlow, MAX_DEVICE_WAIT_SECONDS, type DeviceFlowOptions } from "./device-flow.js";
+export { GatewayIntentReader, INTENT_MS, type IntentReaderOptions } from "./intent-reader.js";
+export { PULL_READ_MS, PublicPullReader } from "./pull-reader.js";

package/dist/types/github/intent-reader.d.ts

@@ -0,0 +1,28 @@
+/**
+ * One small model call that says what a message asks for, made with the asker's own key on the platform's LLM gateway
+ * (OpenAI-compatible `chat/completions`). What it answers decides only what to do, and only after the domain holds it to
+ * the message; it widens no permission. undefined for anything but an answer in time: the rules read the message instead.
+ */
+import { type IntentReader, type ListedMention, type Logger } from "@primusclaw/personal-agent";
+import type { FetchLike } from "./api.js";
+/** Past this the rules read the request instead. */
+export declare const INTENT_MS = 10000;
+export interface IntentReaderOptions {
+    readonly baseUrl: string;
+    readonly model: string;
+    readonly logger: Logger;
+    readonly fetch?: FetchLike;
+    readonly timeoutMs?: number;
+}
+/** The JSON object in what the model wrote; `{ intent: null }` when there is none. */
+export declare function readingOf(content: unknown): Record<string, unknown>;
+export declare class GatewayIntentReader implements IntentReader {
+    private readonly options;
+    private readonly url;
+    private readonly fetchImpl;
+    constructor(options: IntentReaderOptions);
+    read(key: string, text: string, mentions: readonly ListedMention[]): Promise<Record<string, unknown> | undefined>;
+    readMode(key: string, text: string): Promise<Record<string, unknown> | undefined>;
+    readAnswer(key: string, text: string, pending: readonly Readonly<Record<string, string>>[]): Promise<Record<string, unknown> | undefined>;
+    private complete;
+}

package/dist/types/github/pull-reader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Who wrote a pull request (and its title, and the branch it goes into), read from GitHub's public API with no credential.
+ * It exists to refuse early (a committer cannot approve their own pull request); it is not what stops it, Claw is. So any
+ * answer that is not a reading (GitHub down, a rate limit, a pull request that is not there) is "not known".
+ */
+import { type Logger, type PullRef, type PullReader } from "@primusclaw/personal-agent";
+import { GithubApi } from "./api.js";
+/** The one public read of who wrote a pull request: an early answer, never worth a long wait. */
+export declare const PULL_READ_MS = 5000;
+export declare class PublicPullReader implements PullReader {
+    private readonly api;
+    private readonly logger;
+    constructor(api: GithubApi, logger: Logger);
+    private get;
+    repo(owner: string, name: string): Promise<string | undefined>;
+    private pullPath;
+    base(pull: PullRef): Promise<string>;
+    read(pull: PullRef): Promise<{
+        readonly author: string | undefined;
+        readonly title: string;
+    }>;
+}

package/dist/types/http/claw-events.d.ts

@@ -0,0 +1,27 @@
+import type { Clock, ConversationRefRepository, IdempotencyRepository, JsonObject, LinkRepository, Logger, MetricsPort, NotifySubscriptionRepository } from "@primusclaw/personal-agent";
+import { type HttpRoute } from "./routes.js";
+/** The largest event Claw posts, with room (a say of 9000 characters with its sources, or an image carried inline). */
+export declare const MAX_BODY_BYTES: number;
+export declare const MAX_SKEW_SECONDS = 300;
+/** A copy of an event another copy is being sent for waits this long for that send (under Claw's 5 s delivery deadline). */
+export declare const BUSY_WAIT_MS = 3000;
+export declare const BUSY_POLL_MS = 50;
+/** What carries an event into the chat: "delivered", "held", "dropped", ... or "retry" (decided later: Claw sends it again). */
+export type EventSink = (userId: string, reference: JsonObject, event: JsonObject) => Promise<string>;
+export interface ClawEventsDeps {
+    readonly notifySubs: Pick<NotifySubscriptionRepository, "notifySubByRoute">;
+    readonly links: Pick<LinkRepository, "clawUserIdOf">;
+    readonly references: Pick<ConversationRefRepository, "getReference">;
+    readonly claims: Pick<IdempotencyRepository, "claimEvent" | "finishEvent" | "releaseEvent">;
+    readonly deliver: EventSink;
+    readonly clock: Clock;
+    /** TEAMS_CLAW_EVENTS_GONE: an event for a person with no chat here is answered 410 (else 200 "dropped", for an older Claw). */
+    readonly gone: boolean;
+    readonly metrics?: Pick<MetricsPort, "eventDelivered">;
+    readonly logger?: Logger;
+}
+/** `sha256=` HMAC of `<timestamp>.<body>` under the subscription's secret: Claw's signature. */
+export declare function sign(secret: string, timestamp: string, body: Uint8Array): string;
+/** Seconds from when Claw says the event happened (ISO 8601 with a zone) to `nowSeconds`; null when it does not say. */
+export declare function sinceOccurred(occurredAt: unknown, nowSeconds: number): number | null;
+export declare function clawEventsRoute(deps: ClawEventsDeps): HttpRoute;

package/dist/types/http/link.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The account-linking endpoint, reached from the console on the same origin: the console page creates an API key for the
+ * person and posts `{key}` here; the worker answers with a short code that the person types as `/link CODE` in the chat.
+ * The code only ever travels from the console to the chat, so a chat identity can never be tied to a key by a link someone
+ * else sent: anything but `key` in the body is ignored, and nothing is bound here.
+ */
+import { type LinkRepository } from "@primusclaw/personal-agent";
+import { type HttpRoute } from "./routes.js";
+/** Both routes of the link flow live under this prefix, so one ingress path exposes them. */
+export declare const PREFIX = "/primus-claw-agent";
+/** Whether Claw takes `key` (a key Claw refuses gets no code). */
+export type KeyCheck = (key: string) => Promise<boolean>;
+export declare function linkRoute(links: Pick<LinkRepository, "stashPending">, checkKey: KeyCheck): HttpRoute;
+export declare const healthzRoute: HttpRoute;

package/dist/types/http/routes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The worker's HTTP routes, independent of the server library: a route sees the request as read (headers, path
+ * parameters, query, the raw body) and answers with a status and a JSON or text body. The server (`server.ts`) mounts
+ * them; tests call them directly.
+ */
+import { type JsonValue } from "@primusclaw/personal-agent";
+export type Method = "GET" | "POST" | "PUT" | "DELETE";
+export interface HttpRequest {
+    /** Header names lower case. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The path parameters (`:name` in the route's path), decoded. */
+    readonly params: Readonly<Record<string, string>>;
+    readonly query: URLSearchParams;
+    /** The body exactly as it arrived (an HMAC is computed over these bytes). */
+    readonly body: Uint8Array;
+}
+export type HttpResponse = {
+    readonly status: number;
+    readonly json: JsonValue;
+} | {
+    readonly status: number;
+    readonly text: string;
+    readonly contentType?: string;
+};
+export interface HttpRoute {
+    readonly method: Method;
+    /** The path, with `:name` for a parameter (one segment). */
+    readonly path: string;
+    handle(request: HttpRequest): Promise<HttpResponse>;
+}
+export declare function json(status: number, body: JsonValue): HttpResponse;
+/** The body as JSON; undefined when it is not JSON (or not UTF-8). */
+export declare function bodyJson(request: HttpRequest): unknown;
+/** The bearer token of the Authorization header ("" when there is none). */
+export declare function bearerOf(request: HttpRequest): string;
+/** Python's `str(value)` of a JSON value: a string as it is, anything else its repr (`None`, `True`, `{'a': 1}`). */
+export declare function pythonStr(value: unknown): string;

package/dist/types/http/server.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The worker's HTTP server (fastify): the routes it is given, each body read raw (never parsed by the server: a route
+ * that verifies a signature needs the bytes as sent), within a size limit. With an access log, one line per request: its
+ * method, the route it matched as declared (`/claw-events/:route`, never the path as sent, nor its query or body: a path
+ * parameter or a query can carry a token), the status answered and how long it took (the Python worker's `aiohttp.access`).
+ */
+import type { Logger } from "@primusclaw/personal-agent";
+import { type FastifyInstance } from "fastify";
+import type { HttpRoute } from "./routes.js";
+export interface ServerOptions {
+    readonly routes: readonly HttpRoute[];
+    /** The largest body accepted, in bytes (413 beyond it). */
+    readonly maxBodyBytes: number;
+    /** Where the one line per request goes; none: no line. */
+    readonly accessLog?: Logger;
+    /** Routes (as declared) whose line is at debug, not info: a probe that answers every few seconds. */
+    readonly quietRoutes?: readonly string[];
+}
+/** The route a request matched, as declared; a request that matched none is logged as this, never by its path. */
+export declare const UNMATCHED_ROUTE = "(unmatched)";
+/** A server with `routes` mounted; not yet listening. */
+export declare function buildServer(options: ServerOptions): FastifyInstance;
+/** Listen on `host:port`; the port actually bound (for port 0). */
+export declare function listen(app: FastifyInstance, host: string, port: number): Promise<number>;

package/dist/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @primusclaw/personal-agent-runtime: Node implementations of core's ports. It depends on core only (never on a
+ * channel package); a channel package and a deployment's assembly wire these in.
+ */
+export * from "./crypto-random.js";
+export * from "./line-logger.js";
+export * from "./system-clock.js";
+export * from "./context/als-request-scope.js";
+export * from "./claw/index.js";
+export * from "./metrics/index.js";
+export * from "./exchange/index.js";
+export * from "./config/index.js";
+export * from "./crypto/fernet.js";
+export * from "./crypto/link-code.js";
+export * from "./crypto/node-crypto.js";
+export * from "./crypto/py-base64.js";
+export * from "./sqlite/context.js";
+export * from "./sqlite/reencrypt.js";
+export * from "./sqlite/store.js";
+export * from "./sqlite/open.js";
+export * from "./http/routes.js";
+export * from "./http/server.js";
+export * from "./http/link.js";
+export * from "./http/claw-events.js";
+export * from "./github/index.js";
+export * from "./github/feedback-config.js";
+export * from "./github/feedback-issues.js";
+export * from "./github/feedback-worker.js";
+export * from "./logging/chat-log.js";

package/dist/types/line-logger.d.ts

@@ -0,0 +1,15 @@
+import { type LogFields, type Logger, type LogLevel } from "@primusclaw/personal-agent";
+export interface LineLoggerOptions {
+    /** Lines below this level are dropped. */
+    readonly level: LogLevel;
+    /** Where a finished line goes (the process's stderr in production). */
+    readonly write: (line: string) => void;
+    /** The wall clock, for the timestamp. */
+    readonly now: () => number;
+}
+/**
+ * A logger that writes one line per call: `<ISO time> <LEVEL> <message> key=value ...`. The fields of `child` loggers
+ * come first, in the order they were bound. The whole line goes through `redactLogLine`: a net under the rule that a
+ * line carries ids, statuses and kinds of error only (credential shapes and credential-named URL parameters masked).
+ */
+export declare function lineLogger(options: LineLoggerOptions, bound?: LogFields): Logger;

package/dist/types/logging/chat-log.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The worker's last log lines, tagged with the chat they were written for (the Python worker's `feedback.LogBuffer`
+ * and `LOG_SCOPE`): a report's scene shows the reporter's chat's last lines. The router runs each inbound event in the
+ * request scope; every line logged while it is handled (also by what it starts) is kept with that request's user and
+ * conversation, rebuilt from its sentence and its safe fields only (`safeLogText`). A line logged outside any request
+ * is not kept, as Python's `LogBuffer.emit` keeps none while `LOG_SCOPE` is None.
+ */
+import { type Logger, type LogTail, type Mask, type RequestScope } from "@primusclaw/personal-agent";
+export declare class ChatLog implements LogTail {
+    /** Whose message the current task is handling (the router enters it once per inbound event). */
+    private readonly scope;
+    private readonly mask;
+    /** Seconds since the epoch. */
+    private readonly now;
+    private readonly capacity;
+    private readonly lines;
+    constructor(
+    /** Whose message the current task is handling (the router enters it once per inbound event). */
+    scope: RequestScope, mask: Mask, 
+    /** Seconds since the epoch. */
+    now: () => number, capacity?: number);
+    /** `inner`, also keeping each line logged in a chat's scope; `logger` names the part of the worker. */
+    logger(inner: Logger, logger: string): Logger;
+    /** The last lines kept for one chat, oldest first, as the scene shows them. */
+    tail(userId: string, conversationId: string, count?: number): readonly string[];
+}

package/dist/types/metrics/exposition.d.ts

@@ -0,0 +1,17 @@
+/** Numbers and histograms in the Prometheus text format (version 0.0.4), written as the Python worker wrote them. */
+/** Python's `round(value, 3)`: a tie on the exact binary value goes to the even neighbour. */
+export declare function round3(value: number): number;
+/** Python's `repr(float(value))`: the shortest digits, in exponent form below 1e-4 and from 1e16 on. */
+export declare function pyFloatRepr(value: number): string;
+/** A sample's value: a whole number as an integer, anything else as Python's float repr. */
+export declare function formatNumber(value: number): string;
+/** Bucket counts of one histogram series: cumulative buckets, the sum and the count. */
+export declare class Histogram {
+    private readonly buckets;
+    private readonly counts;
+    private total;
+    private count;
+    constructor(buckets: readonly number[]);
+    observe(value: number): void;
+    lines(name: string, labels: string): string[];
+}

package/dist/types/metrics/index.d.ts

@@ -0,0 +1,2 @@
+export { formatNumber, pyFloatRepr, round3 } from "./exposition.js";
+export { ALERTED, CONTENT_TYPE, EVENT_BUCKETS, HELP, LAG_WINDOW_MS, PrometheusMetrics } from "./prometheus-metrics.js";

package/dist/types/metrics/prometheus-metrics.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The worker's counters for the operator's alerts, in memory (they start from zero when the worker restarts), written in
+ * the Prometheus text format for `GET /metrics` on its own port (the listener is the channel's assembly). The text is
+ * the Python worker's, line for line: the alert queries and dashboards read these names and labels.
+ */
+import { type Clock, type MetricsPort, type SecurityEventRecord } from "@primusclaw/personal-agent";
+export declare const CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/** `clawy_inbound_lag_max_ms`: the longest wait of the messages handled in this many milliseconds. */
+export declare const LAG_WINDOW_MS = 60000;
+/** Seconds; the 5 s bucket is the "card within 5 s" line. */
+export declare const EVENT_BUCKETS: readonly [0.5, 1, 2, 3, 5, 10, 30, 60];
+type Labels = ReadonlyArray<readonly [string, string]>;
+/** Series written as 0 from the start, so that each one an alert reads exists before its first event. */
+export declare const ALERTED: ReadonlyArray<readonly [string, Labels]>;
+/** Every metric: its type and help text. */
+export declare const HELP: Readonly<Record<string, readonly [string, string]>>;
+/** The MetricsPort of a worker, kept in memory and written in the Prometheus text format. */
+export declare class PrometheusMetrics implements MetricsPort {
+    private readonly clock;
+    private readonly lagWindowMs;
+    private readonly events;
+    private handledCount;
+    private failedCount;
+    private handleMsTotal;
+    private readonly limits;
+    private readonly dropped;
+    /** (when, lag): decreasing lags, the sliding-window maximum. */
+    private readonly lags;
+    /** Event type -> (receipt to sent, occurred to sent), each written from the start. */
+    private readonly eventTimes;
+    constructor(clock: Clock, lagWindowMs?: number);
+    /** Inbound messages handled so far. */
+    get handled(): number;
+    eventDelivered(eventType: string, handleSeconds: number, sinceOccurredSeconds: number | null): void;
+    securityEvent(record: SecurityEventRecord): void;
+    processed(lagMs: number | null, handleMs: number, ok: boolean): void;
+    limited(reason: string): void;
+    filesDropped(path: string, count?: number): void;
+    /** The longest wait of the messages handled in the window, in milliseconds (0: none). */
+    lagMaxMs(): number;
+    private expire;
+    /** All series in the Prometheus text exposition format (version 0.0.4). */
+    render(): string;
+    private renderHistograms;
+}
+export {};