lingxios 1.0.0

package/dist/src/protocol/constants.js

@@ -0,0 +1,26 @@
+/**
+ * Protocol-wide constants.
+ *
+ * Version numbers gate compatibility between independently deployed pieces
+ * (control plane, workers, kernels). Bump a version only for a breaking wire
+ * change; additive optional fields do not require a bump.
+ */
+/** Control-plane HTTP API and worker claim protocol. */
+export const AGENT_OS_PROTOCOL_VERSION = 2;
+/** Kernel stdio (NDJSON) protocol between the manager and `kernel/runner.py`. */
+export const KERNEL_PROTOCOL_VERSION = 2;
+/**
+ * Each lease attempt of a run owns a disjoint event-sequence range:
+ * `((fence - 1) * RUN_SEQUENCE_SPAN, fence * RUN_SEQUENCE_SPAN]`.
+ *
+ * A retried attempt therefore never collides with — and is never deduplicated
+ * against — events persisted by an earlier attempt of the same run.
+ */
+export const RUN_SEQUENCE_SPAN = 100_000;
+/** Upper bound applied to any single tool/host payload surfaced to the model. */
+export const MAX_TOOL_OUTPUT_CHARS = 8_000;
+/** Name of the single tool exposed to the model. */
+export const IPYTHON_TOOL_NAME = 'ipython';
+/** Name of the in-kernel SDK module the model calls (`host.<capability>.<method>`). */
+export const KERNEL_SDK_MODULE = 'host';
+//# sourceMappingURL=constants.js.map

package/dist/src/protocol/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/protocol/constants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wDAAwD;AACxD,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAU,CAAA;AAEnD,iFAAiF;AACjF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAU,CAAA;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAgB,CAAA;AAEjD,iFAAiF;AACjF,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAc,CAAA;AAEnD,oDAAoD;AACpD,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAkB,CAAA;AAEnD,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAe,CAAA"}

package/dist/src/protocol/kernel-wire.d.ts

@@ -0,0 +1,74 @@
+/**
+ * NDJSON stdio protocol between the kernel manager and `kernel/runner.py`.
+ *
+ * Framing: one JSON object per line, ASCII-safe (non-ASCII escaped) so the
+ * transport is locale-independent (`python -I` ignores PYTHONIOENCODING).
+ *
+ * Concurrency model: the manager serializes executions per kernel; while an
+ * execution is in flight the only messages the manager may write are the
+ * `host_result` replies to that execution's `host_call`s. The runner blocks
+ * synchronously inside a host call, which is what makes the bridge appear as
+ * ordinary synchronous Python to model-authored code.
+ */
+import type { CapabilityGrant, HostDirective, KernelArtifact } from './types.js';
+export interface KernelExecuteRequest {
+    type: 'execute';
+    id: string;
+    code: string;
+    context: {
+        runId: string;
+        cellId: string;
+        capabilities: CapabilityGrant[];
+    };
+}
+export interface KernelHostResultMessage {
+    type: 'host_result';
+    requestId: string;
+    ok: boolean;
+    value?: unknown;
+    error?: string;
+    approval?: {
+        id: string;
+        status: 'PENDING';
+    };
+    directive?: HostDirective;
+}
+export interface KernelShutdownRequest {
+    type: 'shutdown';
+}
+export type ManagerToKernel = KernelExecuteRequest | KernelHostResultMessage | KernelShutdownRequest;
+export interface KernelReadyMessage {
+    type: 'ready';
+    protocol: number;
+    python: string;
+    engine: 'ipython' | 'basic';
+    home: string;
+}
+export interface KernelHostCallMessage {
+    type: 'host_call';
+    /** Execution id this call belongs to — required for correlation. */
+    id: string;
+    requestId: string;
+    callIndex: number;
+    action: string;
+    args: Record<string, unknown>;
+}
+export interface KernelExecutionResultMessage {
+    type: 'execution_result';
+    id: string;
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    result: unknown;
+    error: string | null;
+    approvalId: string | null;
+    truncated: boolean;
+    durationMs: number;
+    artifacts: KernelArtifact[];
+    directives: HostDirective[];
+}
+export interface KernelProtocolErrorMessage {
+    type: 'protocol_error';
+    error: string;
+}
+export type KernelToManager = KernelReadyMessage | KernelHostCallMessage | KernelExecutionResultMessage | KernelProtocolErrorMessage;

package/dist/src/protocol/kernel-wire.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=kernel-wire.js.map

package/dist/src/protocol/kernel-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-wire.js","sourceRoot":"","sources":["../../../src/protocol/kernel-wire.ts"],"names":[],"mappings":""}

package/dist/src/protocol/outcome.d.ts

@@ -0,0 +1,16 @@
+export type Verification = 'passed' | 'not_run' | 'inconclusive';
+export type GoalOutcome = {
+    requestVersion: number;
+    verification: Verification;
+    gaps?: string[];
+    question?: string;
+} & ({
+    status: 'satisfied' | 'partial' | 'awaiting_input' | 'blocked';
+} | {
+    status: 'awaiting_approval';
+    approvalId: string;
+} | {
+    status: 'delegated';
+    taskRef: string;
+});
+export declare function isGoalOutcome(value: unknown): value is GoalOutcome;

package/dist/src/protocol/outcome.js

@@ -0,0 +1,14 @@
+export function isGoalOutcome(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const item = value;
+    return Number.isSafeInteger(item['requestVersion']) && Number(item['requestVersion']) > 0
+        && typeof item['verification'] === 'string' && ['passed', 'not_run', 'inconclusive'].includes(item['verification'])
+        && typeof item['status'] === 'string' && ['satisfied', 'partial', 'awaiting_input', 'awaiting_approval', 'delegated', 'blocked'].includes(item['status'])
+        && (item['gaps'] === undefined || (Array.isArray(item['gaps']) && item['gaps'].every((gap) => typeof gap === 'string')))
+        && (item['question'] === undefined || (item['status'] === 'awaiting_input' && typeof item['question'] === 'string' && item['question'].trim().length > 0 && item['question'].length <= 4_000))
+        && (item['status'] !== 'satisfied' || item['gaps'] === undefined || item['gaps'].length === 0)
+        && (item['status'] !== 'awaiting_approval' || (typeof item['approvalId'] === 'string' && item['approvalId'].trim().length > 0))
+        && (item['status'] !== 'delegated' || (typeof item['taskRef'] === 'string' && item['taskRef'].trim().length > 0));
+}
+//# sourceMappingURL=outcome.js.map

package/dist/src/protocol/outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.js","sourceRoot":"","sources":["../../../src/protocol/outcome.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACrD,MAAM,IAAI,GAAG,KAAgC,CAAA;IAC7C,OAAO,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAAC;WACpF,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,QAAQ,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;WAChH,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;WACtJ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC;WACrH,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,gBAAgB,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;WAC3L,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,WAAW,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,SAAS,IAAK,IAAI,CAAC,MAAM,CAAe,CAAC,MAAM,KAAK,CAAC,CAAC;WAC1G,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,mBAAmB,IAAI,CAAC,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;WAC5H,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,WAAW,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAA;AACrH,CAAC"}

package/dist/src/protocol/types.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Core protocol types shared by the control plane, workers, kernels, and
+ * extensions. This module is intentionally logic-free: every layer depends on
+ * it and it depends on nothing.
+ */
+/**
+ * Why a work item exists. `turn` is the ordinary conversational turn handled
+ * by the runtime's agent loop; every other kind is routed to a registered
+ * {@link import('../runtime/runtime.js').WorkProcessor}.
+ */
+export type WorkKind = 'turn' | 'resume' | (string & {});
+/** Scheduling lane. Higher lanes are claimed before lower ones. */
+export type WorkLane = 'interactive' | 'approval' | 'collaboration' | 'background';
+export declare const WORK_LANE_PRIORITY: Readonly<Record<WorkLane, number>>;
+export type WorkStatus = 'queued' | 'leased' | 'completed' | 'failed' | 'cancelled';
+/**
+ * A durable unit of agent work, claimed under a fenced lease.
+ *
+ * Invariants:
+ * - `fence` increases by exactly one on every lease acquisition and every
+ *   yield, and never decreases. Every mutating control-plane call carries
+ *   `(id, fence, leaseToken)` and is rejected unless all three match the
+ *   current lease.
+ * - `id` doubles as the run id: a retried attempt reuses every externally
+ *   visible identity, and attempt separation happens through the fence-scoped
+ *   event-sequence ranges (see `RUN_SEQUENCE_SPAN`).
+ */
+export interface WorkItem {
+    id: string;
+    fence: number;
+    /**
+     * Increments when the session is re-routed to a different worker, so a
+     * kernel filesystem home written by a lost worker is never reused.
+     */
+    homeEpoch: number;
+    tenantId: string;
+    agentId: string;
+    sessionId: string;
+    /** Optional sub-thread inside the session. */
+    threadId?: string;
+    kind: WorkKind;
+    lane: WorkLane;
+    /** Opaque reference to whatever triggered this work (message id, cron id…). */
+    triggerRef: string;
+    /** Human principal whose authorization the work runs under, if any. */
+    principalId?: string;
+    createdAt?: string;
+    availableAt?: string;
+    attempts?: number;
+    preemptions?: number;
+    /** Bearer proof of the current lease. Never persisted in clear text. */
+    leaseToken: string;
+    /** Deployment-defined extra routing/context payload (opaque to the core). */
+    meta?: Record<string, unknown>;
+}
+export interface WorkCompletion {
+    goalOutcome?: import('./outcome.js').GoalOutcome;
+    status: 'completed' | 'failed' | 'cancelled';
+    resultText?: string;
+    error?: string;
+}
+/**
+ * A capability grants access to one host-bridge namespace, optionally
+ * restricted to specific methods. Grants are enforced twice: advisorily
+ * inside the kernel (the model cannot even *name* an ungranted method) and
+ * authoritatively in the control plane before any action executes.
+ */
+export interface CapabilityGrant {
+    name: string;
+    /** When present, only these methods are callable. */
+    methods?: readonly string[];
+}
+/**
+ * One product side effect requested by kernel code via
+ * `host.<namespace>.<method>(...)`.
+ *
+ * `idempotencyKey` is the JSON tuple `[runId, cellId, callIndex]` — deterministic
+ * across kernel restarts replaying the same cell — so the control-plane
+ * action ledger can reject changed intents and avoid blindly replaying effects.
+ */
+export interface HostAction {
+    runId: string;
+    cellId: string;
+    callIndex: number;
+    /** `<namespace>.<method>` */
+    action: string;
+    args: Record<string, unknown>;
+    idempotencyKey: string;
+}
+export declare function actionKeyOf(action: Pick<HostAction, 'runId' | 'cellId' | 'callIndex'>): string;
+export interface HostActionResult {
+    ok: boolean;
+    executionState?: 'unknown';
+    value?: unknown;
+    error?: string;
+    /** Present when the action suspended into a human approval. */
+    approval?: {
+        id: string;
+        status: 'PENDING';
+    };
+    /** Optional host instruction back to the runtime. */
+    directive?: HostDirective;
+}
+/**
+ * A host directive lets an action tell the runtime that the turn is finished
+ * out-of-band (e.g. work was handed to another surface, or the host asked the
+ * user a blocking question). The runtime completes the run successfully
+ * without a final assistant message.
+ */
+export interface HostDirective {
+    type: 'defer' | 'task_contract';
+    reason?: string;
+    data?: Record<string, unknown>;
+}
+export interface ApprovalResolution {
+    approvalId: string;
+    approved: boolean;
+    result?: unknown;
+    error?: string;
+}
+export interface KernelArtifact {
+    path: string;
+    size: number;
+    mime: string;
+    sha256: string;
+}
+export interface KernelExecution {
+    executionId: string;
+    stdout: string;
+    stderr: string;
+    result: unknown;
+    durationMs: number;
+    truncated: boolean;
+    artifacts: KernelArtifact[];
+    directives: HostDirective[];
+}
+export type RunStage = 'started' | 'delta' | 'completed' | 'failed' | 'cancelled';
+/**
+ * A single durable event of a run attempt. `seq` must fall inside the
+ * attempt's fence-scoped range; the control plane rejects events outside it
+ * and deduplicates on `(runId, seq)`.
+ */
+export interface RunEvent {
+    runId: string;
+    seq: number;
+    kind: string;
+    stage: RunStage;
+    /** `user` events may be surfaced to end users; `internal` never are. */
+    visibility: 'user' | 'internal';
+    data: Record<string, unknown>;
+}
+export type ModelItem = {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+} | {
+    type: 'function_call';
+    callId: string;
+    name: string;
+    arguments: string;
+} | {
+    type: 'function_call_output';
+    callId: string;
+    output: string;
+};
+/**
+ * Durable conversational state of one agent session, saved with optimistic
+ * concurrency (`revision`).
+ */
+export interface SessionRecord {
+    request?: import('../context/request.js').RequestSnapshot;
+    key: string;
+    tenantId: string;
+    agentId: string;
+    sessionId: string;
+    threadId?: string;
+    summary?: string;
+    history: ModelItem[];
+    /** Work ids whose turn input is already folded into `history`. */
+    appliedWorkIds: string[];
+    revision: number;
+    compactionEpoch: number;
+    /** Frozen system-prompt context; rebuilt when its source versions change. */
+    promptContext?: PromptContext;
+}
+/** Composite key shared by sessions, kernel affinity, and lease exclusivity. */
+export declare function sessionKeyOf(work: Pick<WorkItem, 'tenantId' | 'agentId' | 'sessionId' | 'threadId'>): string;
+/**
+ * The cache-stable prefix of the model conversation. Frozen into the session
+ * and only rebuilt when a source version changes, so provider prompt caches
+ * stay warm across turns.
+ */
+export interface PromptContext {
+    version: 2;
+    epoch: number;
+    assembledAt: string;
+    systemInstructions: string;
+    persona: {
+        name: string;
+        role: string;
+        instructions: string;
+    };
+    capabilities: string[];
+    /** Versions of everything folded into `systemInstructions`. */
+    sourceVersions: Record<string, string>;
+}
+export interface ContextMessage {
+    ref: string;
+    authorId: string;
+    authorName: string;
+    authorKind: 'human' | 'agent' | 'system';
+    body: string;
+    createdAt: string;
+    replyToRef?: string;
+}
+/**
+ * Everything the runtime needs to run one attempt. Split into a cache-stable
+ * candidate prompt context and per-turn dynamic context that is never frozen
+ * into the session.
+ */
+export interface TurnContext {
+    memory?: import('../memory/store.js').MemorySnapshot;
+    /** Prior attempt records only; files must be rechecked before current delivery. */
+    priorArtifacts?: KernelArtifact[];
+    evidence?: import('../context/evidence.js').EvidenceItem[];
+    work: WorkItem;
+    persona: {
+        name: string;
+        role: string;
+        instructions: string;
+    };
+    capabilities: string[];
+    messages: ContextMessage[];
+    promptContextCandidate?: PromptContext;
+    pendingApproval?: ApprovalResolution;
+    /**
+     * Deployment-defined per-turn context (retrieval results, live product
+     * state…). Rendered by the active RuntimePolicy; opaque to the core.
+     */
+    dynamic?: Record<string, unknown>;
+}
+export interface SteerInput {
+    id: string;
+    text: string;
+    createdAt: string;
+    attachments?: import('../context/attachments.js').RequestAttachment[];
+}
+export interface HeartbeatResult {
+    ok: boolean;
+    cancelRequested?: boolean;
+    preemptRequested?: boolean;
+    steer?: SteerInput[];
+}
+/**
+ * The final user-visible assistant message of a turn. The control plane
+ * verifies `body` byte-for-byte against the durably streamed deltas of the
+ * same attempt before delivering it.
+ */
+export interface AssistantMessage {
+    envelope: import('../outcome/envelope.js').ResponseEnvelope;
+    version: 2;
+    runId: string;
+    agentId: string;
+    sessionId: string;
+    threadId?: string;
+    body: string;
+}

package/dist/src/protocol/types.js

@@ -0,0 +1,19 @@
+/**
+ * Core protocol types shared by the control plane, workers, kernels, and
+ * extensions. This module is intentionally logic-free: every layer depends on
+ * it and it depends on nothing.
+ */
+export const WORK_LANE_PRIORITY = Object.freeze({
+    interactive: 4,
+    approval: 3,
+    collaboration: 2,
+    background: 1,
+});
+export function actionKeyOf(action) {
+    return JSON.stringify([action.runId, action.cellId, action.callIndex]);
+}
+/** Composite key shared by sessions, kernel affinity, and lease exclusivity. */
+export function sessionKeyOf(work) {
+    return JSON.stringify([work.tenantId, work.agentId, work.sessionId, work.threadId ?? null]);
+}
+//# sourceMappingURL=types.js.map

package/dist/src/protocol/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/protocol/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgBH,MAAM,CAAC,MAAM,kBAAkB,GAAuC,MAAM,CAAC,MAAM,CAAC;IAClF,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,aAAa,EAAE,CAAC;IAChB,UAAU,EAAE,CAAC;CACd,CAAC,CAAA;AA0FF,MAAM,UAAU,WAAW,CAAC,MAA0D;IACpF,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAA;AACxE,CAAC;AAyGD,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,IAAuE;IAClG,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAA;AAC7F,CAAC"}

package/dist/src/research/address.d.ts

@@ -0,0 +1,2 @@
+export declare function isPublicAddress(address: string): boolean;
+export declare function researchUrl(raw: string): URL;

package/dist/src/research/address.js

@@ -0,0 +1,32 @@
+import { BlockList, isIP } from 'node:net';
+const blocked = new BlockList();
+for (const [address, prefix] of [
+    ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
+    ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24],
+    ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24],
+    ['224.0.0.0', 4], ['240.0.0.0', 4],
+])
+    blocked.addSubnet(address, prefix, 'ipv4');
+const globalV6 = new BlockList();
+globalV6.addSubnet('2000::', 3, 'ipv6');
+for (const [address, prefix] of [['2001::', 23], ['2001:db8::', 32], ['2002::', 16], ['3fff::', 20]]) {
+    blocked.addSubnet(address, prefix, 'ipv6');
+}
+export function isPublicAddress(address) {
+    const family = isIP(address);
+    if (family === 4)
+        return !blocked.check(address, 'ipv4');
+    return family === 6 && globalV6.check(address, 'ipv6') && !blocked.check(address, 'ipv6');
+}
+export function researchUrl(raw) {
+    if (raw.length > 2048)
+        throw new Error('research URL is too long');
+    const url = new URL(raw);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+        throw new Error('research URL requires HTTP(S) without credentials');
+    const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (!host || host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local') || (isIP(host) && !isPublicAddress(host)))
+        throw new Error('research URL host is blocked');
+    return url;
+}
+//# sourceMappingURL=address.js.map

package/dist/src/research/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../../src/research/address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAE1C,MAAM,OAAO,GAAG,IAAI,SAAS,EAAE,CAAA;AAC/B,KAAK,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI;IAC9B,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC,aAAa,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;IAC7E,CAAC,aAAa,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC;IAClF,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;CAC1B;IAAE,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AACtD,MAAM,QAAQ,GAAG,IAAI,SAAS,EAAE,CAAA;AAChC,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,MAAM,CAAC,CAAA;AACvC,KAAK,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAU,EAAE,CAAC;IAC9G,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAA;IAC5B,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACxD,OAAO,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAC3F,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAA;IAClE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;IACxB,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;IACrJ,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IAC/D,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAA;IACtL,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/src/research/fetch.d.ts

@@ -0,0 +1,7 @@
+import { type RequestOptions } from 'node:https';
+export declare function pinnedRequestOptions(url: URL, address: string): RequestOptions;
+export declare function fetchResearch(raw: string): Promise<{
+    url: string;
+    contentType: string;
+    body: Buffer;
+}>;

package/dist/src/research/fetch.js

@@ -0,0 +1,83 @@
+import { lookup } from 'node:dns/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { isIP } from 'node:net';
+import { isPublicAddress, researchUrl } from './address.js';
+const MAX_BYTES = 2 * 1024 * 1024;
+export function pinnedRequestOptions(url, address) {
+    if (!isPublicAddress(address))
+        throw new Error('research address is blocked');
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    return { hostname: address, agent: false,
+        ...(!isIP(host) ? { servername: host } : {}),
+        headers: { host: url.host, accept: 'text/html,application/json,text/plain', 'accept-encoding': 'identity', 'user-agent': 'LingxiOS-Research/1.0' },
+    };
+}
+export async function fetchResearch(raw) {
+    const controller = new AbortController();
+    let timeout;
+    const expired = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => { controller.abort(); reject(new Error('research request timed out')); }, 15_000);
+    });
+    try {
+        return await Promise.race([expired, (async () => {
+                let url = researchUrl(raw);
+                for (let redirects = 0; redirects <= 5; redirects++) {
+                    const host = url.hostname.replace(/^\[|\]$/g, '');
+                    const addresses = isIP(host) ? [{ address: host }] : await lookup(host, { all: true, verbatim: true });
+                    if (!addresses.length || addresses.some(item => !isPublicAddress(item.address)))
+                        throw new Error('research DNS resolved to a blocked address');
+                    controller.signal.throwIfAborted();
+                    const result = await new Promise((resolve, reject) => {
+                        const request = (url.protocol === 'https:' ? httpsRequest : httpRequest)(url, {
+                            ...pinnedRequestOptions(url, addresses[0].address), signal: controller.signal,
+                        }, response => {
+                            const status = response.statusCode ?? 0;
+                            if (status >= 300 && status < 400) {
+                                const location = response.headers.location;
+                                response.destroy();
+                                if (!location)
+                                    reject(new Error('research redirect has no location'));
+                                else
+                                    resolve({ redirect: location });
+                                return;
+                            }
+                            if (status < 200 || status >= 300 || Number(response.headers['content-length'] ?? 0) > MAX_BYTES) {
+                                response.destroy();
+                                reject(new Error(`research response rejected (HTTP ${status}, size limit ${MAX_BYTES})`));
+                                return;
+                            }
+                            if (response.headers['content-encoding'] && response.headers['content-encoding'] !== 'identity') {
+                                response.destroy();
+                                reject(new Error('research source returned unsupported content encoding'));
+                                return;
+                            }
+                            const chunks = [];
+                            let size = 0;
+                            response.on('data', (chunk) => {
+                                size += chunk.length;
+                                if (size > MAX_BYTES)
+                                    response.destroy(new Error('research source exceeds 2 MiB'));
+                                else
+                                    chunks.push(chunk);
+                            });
+                            response.on('error', reject);
+                            response.on('end', () => resolve({ url: url.href, contentType: String(response.headers['content-type'] ?? 'application/octet-stream').split(';')[0].toLowerCase(), body: Buffer.concat(chunks) }));
+                        });
+                        request.on('error', reject);
+                        request.end();
+                    });
+                    if (!('redirect' in result))
+                        return result;
+                    if (redirects === 5)
+                        throw new Error('research source redirected too many times');
+                    url = researchUrl(new URL(result.redirect, url).href);
+                }
+                throw new Error('research redirect limit exceeded');
+            })()]);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+//# sourceMappingURL=fetch.js.map

package/dist/src/research/fetch.js.map

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

package/dist/src/research/index.d.ts

@@ -0,0 +1,26 @@
+export interface ResearchSearchResult {
+    title: string;
+    url: string;
+    doi?: string;
+    publicationYear?: number;
+    authors: string[];
+    abstract?: string;
+    citedByCount?: number;
+    source: 'OpenAlex';
+}
+export declare function searchResearch(query: string, limit?: number): Promise<{
+    provider: 'OpenAlex';
+    query: string;
+    results: ResearchSearchResult[];
+}>;
+export declare function parseOpenAlex(value: unknown, count: number): ResearchSearchResult[];
+export declare function decodeHtml(value: string): string;
+export declare function readResearch(rawUrl: string): Promise<{
+    url: string;
+    finalUrl: string;
+    contentType: string;
+    text: string;
+    bytes: number;
+    sha256: string;
+    truncated: boolean;
+}>;