@autorag/librarian 2.0.0 → 2.1.0

package/dist/datasource/chunk-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Persistent chunk store shared by the connector-backed datasource skills.
+ *
+ * Documents fetched by a {@link DatasourceConnector} are split into bounded
+ * chunks, persisted as JSON under
+ * `<workspaceRoot>/.autorag/datasources/<skill>/<instance>/chunks.json`, and
+ * searched with a lightweight BM25-style lexical scorer. The store never
+ * throws from load/search; persistence failures degrade to in-memory-only
+ * operation.
+ */
+import type { ConnectorDocument } from "./connector.js";
+export interface StoredChunk {
+    readonly chunkId: string;
+    readonly docId: string;
+    /** Sanitized hierarchy segments under the instance root. */
+    readonly hierarchy: readonly string[];
+    readonly title?: string;
+    readonly content: string;
+    readonly publishedAt?: number;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface ScoredChunk {
+    readonly chunk: StoredChunk;
+    readonly score: number;
+}
+export interface DatasourceChunkStoreOptions {
+    readonly skillName: string;
+    readonly instanceId: string;
+    /** When set, chunks are persisted under `.autorag/datasources/…`. */
+    readonly workspaceRoot?: string;
+    /** Maximum characters per chunk. Default 2000. */
+    readonly maxChunkChars?: number;
+}
+export declare function datasourceChunkStorePath(workspaceRoot: string, skillName: string, instanceId: string): string;
+export declare class DatasourceChunkStore {
+    private readonly skillName;
+    private readonly instanceId;
+    private readonly storePath;
+    private readonly maxChunkChars;
+    private chunkList;
+    private loaded;
+    constructor(options: DatasourceChunkStoreOptions);
+    /**
+     * Replace the store contents with chunks derived from `documents`.
+     * Returns the resulting chunk count. Persistence failures are swallowed
+     * (in-memory contents stay authoritative for this process).
+     */
+    replaceDocuments(documents: readonly ConnectorDocument[]): number;
+    /** Load persisted chunks when present. Returns true when data was loaded. */
+    load(): boolean;
+    /** Ensure persisted chunks are loaded once for read paths. */
+    ensureLoaded(): void;
+    chunks(): readonly StoredChunk[];
+    /** Distinct hierarchy prefixes present in the store (for source listing). */
+    hierarchies(): readonly (readonly string[])[];
+    /**
+     * BM25-style lexical search over the stored chunks. Empty queries and
+     * empty stores return `[]`; this method never throws.
+     *
+     * Terms match document tokens exactly or as a prefix (min 2 chars), so
+     * agglutinative suffixes — Korean particles/endings (인증서 → 인증서를) and
+     * English inflections (index → indexing) — still rank. Prefix hits are
+     * slightly discounted against exact hits.
+     */
+    search(query: string, topK: number): readonly ScoredChunk[];
+    private persist;
+}

package/dist/datasource/connector-skill.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Shared {@link DatasourceSkill} implementation for connector-backed
+ * datasources (Slack, Discord, Notion, GitHub, Google Drive, Gmail/IMAP,
+ * local mail exports, Obsidian vaults, RSS/news).
+ *
+ * Composition: a trusted {@link DatasourceConnector} fetches documents, a
+ * {@link DatasourceChunkStore} persists and lexically indexes them, and this
+ * class exposes the standard skill surface — descriptor, polling metadata,
+ * ok/fail indexing with traceable diagnostics, retrieval methods routed
+ * through the shared pipeline, source descriptions, and a
+ * progressive-disclosure agent-skill manifest.
+ *
+ * Invariants:
+ *  - Constructed only from trusted, server-supplied configuration.
+ *  - Sources are stable slash-hierarchical paths `/<skill>/<instance>/…`.
+ *  - `index()` never throws; failures surface as traceable diagnostics.
+ *  - Retrieval honors `scope` and `allowedScopes` narrowing; tool arguments
+ *    can never widen access (enforced upstream by DatasourceAccessContext).
+ *  - Results and metadata may carry real file paths or account identifiers;
+ *    privacy is the operator's responsibility (use a local LLM).
+ */
+import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
+import { DatasourceChunkStore } from "./chunk-store.js";
+import type { DatasourceConnector } from "./connector.js";
+import type { DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "./types.js";
+/** Static identity/behavior shared by all instances of one skill kind. */
+export interface ConnectorSkillDefinition {
+    /** Stable skill name and datasource id, e.g. `"slack"`. */
+    readonly skillName: string;
+    /** Skill kind, e.g. `"slack-workspace"`. */
+    readonly skillType: string;
+    /** One-line descriptor description. */
+    readonly description: string;
+    /** Capability tags such as `"chat"`, `"api"`, `"polling"`. */
+    readonly capabilities: readonly string[];
+    /** Default authorization tags when the server config supplies none. */
+    readonly defaultTags: readonly string[];
+    /** Content type reported on source descriptions, e.g. `"chat"`. */
+    readonly contentType: string;
+    /** Short "when to use" text for the system-prompt skills block. */
+    readonly manifestDescription: string;
+    /** Extra path-opaque manifest body lines (after the standard sections). */
+    readonly manifestNotes?: readonly string[];
+}
+export interface ConnectorSkillOptions {
+    readonly connector: DatasourceConnector;
+    readonly instanceId?: string;
+    readonly instances?: readonly string[];
+    /** Poll interval in ms. Default 15 minutes; `0` disables polling. */
+    readonly pollingIntervalMs?: number;
+    readonly tags?: readonly string[];
+    readonly lastIndexedAt?: number;
+    /** Workspace root for chunk persistence; omitted ⇒ in-memory only. */
+    readonly workspaceRoot?: string;
+    readonly maxChunkChars?: number;
+    /**
+     * Dedupe window in ms: when > 0, documents whose `docId` was already
+     * indexed within the window keep their previous timestamp identity and
+     * duplicates inside one fetch are dropped (RSS/news re-delivery).
+     */
+    readonly dedupeWindowMs?: number;
+}
+export declare class ConnectorDatasourceSkill implements DatasourceSkill {
+    protected readonly definition: ConnectorSkillDefinition;
+    protected readonly connector: DatasourceConnector;
+    protected readonly instanceId: string;
+    protected readonly instances: readonly string[];
+    protected readonly pollingIntervalMs: number;
+    protected readonly tags: readonly string[];
+    protected readonly store: DatasourceChunkStore;
+    protected readonly dedupeWindowMs: number;
+    private lastIndexedAt;
+    private lastPolledAt;
+    private lastError;
+    /** docId → last-seen epoch ms, for the dedupe window. */
+    private readonly seenDocs;
+    constructor(definition: ConnectorSkillDefinition, options: ConnectorSkillOptions);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+    private applyDedupeWindow;
+    private fail;
+}
+interface ConnectorLexicalMethodOptions {
+    readonly skillName: string;
+    readonly skillType: string;
+    readonly instanceId: string;
+    readonly tags: readonly string[];
+    readonly store: DatasourceChunkStore;
+}
+/**
+ * Lexical retrieval over a connector skill's chunk store. Failures collapse
+ * to an empty result set; retrieval never throws. Sources are opaque
+ * `/<skill>/<instance>/chunks/<chunk-id>` paths and are matched against both
+ * the user scope and the trusted allowed scopes.
+ */
+export declare class ConnectorLexicalMethod implements RetrievalMethod {
+    private readonly options;
+    constructor(options: ConnectorLexicalMethodOptions);
+    describe(): RetrievalMethodDescriptor;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    private matchesScope;
+}
+export {};

package/dist/datasource/connector.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Connector contract shared by the built-in datasource skills (Slack, Discord,
+ * Notion, GitHub, Google Drive, Gmail/IMAP, local mail exports, Obsidian,
+ * RSS/news).
+ *
+ * A *connector* is the trusted, server-configured bridge to one external
+ * system. It fetches documents for indexing and NEVER throws — every failure
+ * is reported as a discriminated `ok: false` result with a coarse
+ * {@link ConnectorFailureReason} and a traceable diagnostic message.
+ * Connectors are constructed from server-supplied configuration only;
+ * model/tool arguments never reach a connector.
+ */
+import type { DatasourceDiagnosticCode } from "./types.js";
+/** Coarse failure classes a connector can report. */
+export type ConnectorFailureReason = "not-configured" | "auth" | "permission" | "rate-limited" | "unavailable" | "api-error" | "invalid-data" | "empty";
+/**
+ * One document fetched from the external system. `docId` and `hierarchy`
+ * segments are sanitized into opaque slash-safe segments before they become
+ * part of a source path.
+ */
+export interface ConnectorDocument {
+    /** Stable, unique id within the connector instance (pre-sanitization). */
+    readonly docId: string;
+    /**
+     * Optional hierarchy segments under the instance root, e.g.
+     * `["channels", "general"]` for a Slack channel or
+     * `["folders", "projects"]` for a vault folder.
+     */
+    readonly hierarchy?: readonly string[];
+    readonly title?: string;
+    readonly content: string;
+    /** Epoch milliseconds of the document's own timestamp when known. */
+    readonly publishedAt?: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ConnectorFetchOk {
+    readonly ok: true;
+    readonly documents: readonly ConnectorDocument[];
+    /** Sanitized, path/PII-opaque warning strings. */
+    readonly warnings?: readonly string[];
+}
+export interface ConnectorFetchFail {
+    readonly ok: false;
+    readonly reason: ConnectorFailureReason;
+    /** Sanitized, path/PII-opaque failure message. */
+    readonly message?: string;
+}
+export type ConnectorFetchResult = ConnectorFetchOk | ConnectorFetchFail;
+/**
+ * The trusted bridge to one external system. Implementations never throw from
+ * `fetch` — they return an `ok: false` result instead.
+ */
+export interface DatasourceConnector {
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+}
+/** Map a connector failure reason onto the datasource diagnostic union. */
+export declare function connectorFailureToDiagnosticCode(reason: ConnectorFailureReason): DatasourceDiagnosticCode;
+/**
+ * Bound free-form diagnostic text: trimmed and capped at 500 characters.
+ * Diagnostic messages are passed through verbatim (paths, account ids, and
+ * all) so failures stay traceable; privacy is the operator's responsibility
+ * (run AutoRAG with a local LLM if diagnostics must not leave the machine).
+ */
+export declare function boundDiagnosticText(value: string): string;
+/**
+ * Sanitize an arbitrary string into a slash-safe source-path segment.
+ * Unicode letters/digits (e.g. Hangul channel or folder names) are kept so
+ * scopes stay human-readable; separators, punctuation, and control chars
+ * collapse to `-`. When sanitization loses information, a short hash of the
+ * original value is appended so distinct inputs stay distinct.
+ */
+export declare function sanitizeIdSegment(value: string): string;

package/dist/datasource/http.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Minimal HTTP helper shared by the API-backed datasource connectors.
+ *
+ * Every request is bounded by a timeout, honors an optional outer abort
+ * signal, and maps failures onto the coarse {@link ConnectorFailureReason}
+ * union with short, path/PII-opaque messages (never URLs, tokens, or bodies).
+ */
+import type { ConnectorFailureReason } from "./connector.js";
+export interface HttpRequestOptions {
+    readonly fetchImpl?: typeof fetch;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly method?: string;
+    readonly body?: string;
+}
+export type HttpJsonResult = {
+    readonly ok: true;
+    readonly status: number;
+    readonly json: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: ConnectorFailureReason;
+    readonly message: string;
+};
+export type HttpTextResult = {
+    readonly ok: true;
+    readonly status: number;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly reason: ConnectorFailureReason;
+    readonly message: string;
+};
+/** Map an HTTP status code onto a connector failure reason. */
+export declare function statusToReason(status: number): ConnectorFailureReason;
+/** GET/POST a URL and return the body text; never throws. */
+export declare function httpText(url: string, options?: HttpRequestOptions): Promise<HttpTextResult>;
+/** GET/POST a URL and parse the body as JSON; never throws. */
+export declare function httpJson(url: string, options?: HttpRequestOptions): Promise<HttpJsonResult>;
+/** Narrowing helpers for defensive JSON traversal. */
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function asArray(value: unknown): readonly unknown[];
+export declare function asString(value: unknown): string | undefined;
+export declare function asNumber(value: unknown): number | undefined;
+/** Parse a date-ish string to epoch ms, or undefined. */
+export declare function parseEpochMs(value: unknown): number | undefined;
+/** Resolve an auth token from explicit config or an environment variable name. */
+export declare function resolveToken(token: string | undefined, tokenEnv: string | undefined): string | undefined;

package/dist/datasource/index.d.ts

@@ -1,9 +1,23 @@
 export { DatasourceAccessContext, type DatasourceAccessContextOptions } from "./access-context.js";
+export { DatasourceChunkStore, type DatasourceChunkStoreOptions, datasourceChunkStorePath, type ScoredChunk, type StoredChunk, } from "./chunk-store.js";
+export { boundDiagnosticText, type ConnectorDocument, type ConnectorFailureReason, type ConnectorFetchFail, type ConnectorFetchOk, type ConnectorFetchResult, connectorFailureToDiagnosticCode, type DatasourceConnector, sanitizeIdSegment, } from "./connector.js";
+export { ConnectorDatasourceSkill, ConnectorLexicalMethod, type ConnectorSkillDefinition, type ConnectorSkillOptions, } from "./connector-skill.js";
 export { mapDatasourceDiagnostic, mapDatasourceDiagnostics } from "./diagnostics.js";
 export { type CronParseResult, isDue, parseCronExpr } from "./polling.js";
 export { DatasourceSkillRegistry, type RegisteredDatasourceSkill } from "./registry.js";
 export { DatasourceResultFilter, type ResultsByMethod } from "./result-filter.js";
 export { buildDatasourceChunkSource, buildDatasourceInstanceSource, DATASOURCE_CHUNKS_SEGMENT, datasourceSourceHasFragment, datasourceSourcePath, isDatasourceSource, matchesDatasourceScope, matchesVirtualPathScope, normalizeVirtualPath, } from "./scope.js";
+export { DiscordConnector, type DiscordConnectorOptions, DiscordSkill, type DiscordSkillOptions, } from "./skills/discord/index.js";
+export { BUILTIN_DATASOURCE_SKILL_NAMES, type BuildDatasourceSkillsResult, buildDatasourceSkills, type DatasourceSkillConfig, type DatasourcesConfig, } from "./skills/factory.js";
+export { GDriveConnector, type GDriveConnectorOptions, GDriveSkill, type GDriveSkillOptions, } from "./skills/gdrive/index.js";
+export { GitHubConnector, type GitHubConnectorOptions, GitHubSkill, type GitHubSkillOptions, } from "./skills/github/index.js";
+export { GmailConnector, type GmailConnectorOptions, GmailSkill, type GmailSkillOptions, } from "./skills/gmail/index.js";
 export type { KatokFailureReason, KatokHit, KatokOptions, KatokSearchMode, KatokSearchOptions, KatokSearchResult, KatokSkillClient, KatokSkillOptions, } from "./skills/katok/index.js";
 export { KatokBm25Method, KatokClient, KatokSemanticMethod, KatokSkill } from "./skills/katok/index.js";
+export { MailExportConnector, type MailExportConnectorOptions, MailExportSkill, type MailExportSkillOptions, } from "./skills/mail-export/index.js";
+export { NotionConnector, type NotionConnectorOptions, NotionSkill, type NotionSkillOptions, } from "./skills/notion/index.js";
+export { ObsidianConnector, type ObsidianConnectorOptions, ObsidianSkill, type ObsidianSkillOptions, } from "./skills/obsidian/index.js";
+export { RssConnector, type RssConnectorOptions, type RssFeedConfig, RssSkill, type RssSkillOptions, } from "./skills/rss/index.js";
+export { SlackConnector, type SlackConnectorOptions, SlackSkill, type SlackSkillOptions, } from "./skills/slack/index.js";
+export { SpotlightConnector, type SpotlightConnectorOptions, SpotlightSkill, type SpotlightSkillOptions, } from "./skills/spotlight/index.js";
 export type { DatasourceAccessible, DatasourceDiagnostic, DatasourceDiagnosticCode, DatasourceIndexFail, DatasourceIndexOk, DatasourceIndexResult, DatasourceInstance, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription, } from "./types.js";

package/dist/datasource/skills/discord/connector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Discord guild connector (issue #1305).
+ *
+ * Fetches text/announcement channel history through the Discord REST API
+ * using a trusted, server-configured bot token. Per-channel permission
+ * failures degrade to warnings; a guild-level 429 fails the whole fetch as
+ * rate-limited. Never throws; all messages stay path/PII-opaque.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface DiscordConnectorOptions {
+    /** Discord REST base; override to point at a mock server in tests. */
+    readonly baseUrl?: string;
+    /** Bot token; explicit value wins over {@link tokenEnv}. */
+    readonly token?: string;
+    /** Env var name holding the bot token. Default `DISCORD_BOT_TOKEN`. */
+    readonly tokenEnv?: string;
+    /** Guild (server) id to index. Required trusted configuration. */
+    readonly guildId?: string;
+    /** Restrict indexing to these channel names or ids. */
+    readonly channels?: readonly string[];
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly maxPages?: number;
+    readonly maxDocuments?: number;
+}
+export declare class DiscordConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: DiscordConnectorOptions);
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/discord/index.d.ts

@@ -0,0 +1,2 @@
+export { DiscordConnector, type DiscordConnectorOptions } from "./connector.js";
+export { DISCORD_SKILL_DEFINITION, DiscordSkill, type DiscordSkillOptions } from "./skill.js";

package/dist/datasource/skills/discord/skill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Discord guild datasource skill (issue #1305).
+ *
+ * Thin composition of DiscordConnector with the shared
+ * {@link ConnectorDatasourceSkill} base: descriptor, polling metadata,
+ * ok/fail indexing with path/PII-opaque diagnostics, lexical retrieval via
+ * the shared pipeline, opaque `/discord/<instance>/…` sources, and a
+ * progressive-disclosure agent-skill manifest.
+ */
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { DiscordConnector, type DiscordConnectorOptions } from "./connector.js";
+export declare const DISCORD_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface DiscordSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: DiscordConnector;
+    readonly connectorOptions?: DiscordConnectorOptions;
+}
+export declare class DiscordSkill extends ConnectorDatasourceSkill {
+    constructor(options?: DiscordSkillOptions);
+}

package/dist/datasource/skills/factory.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Config-driven factory for the built-in connector-backed datasource skills.
+ *
+ * The CLI/server layer passes the trusted `datasources` section of
+ * `config.json`; this factory materializes one skill per configured entry.
+ * Model/tool arguments never reach this factory — it is part of the trusted
+ * configuration path. Unknown skill names and disabled entries are skipped
+ * and reported so setup surfaces actionable (but path-opaque) feedback.
+ */
+import type { DatasourceSkill } from "../types.js";
+/** One configured datasource entry (the trusted `datasources.<name>` value). */
+export interface DatasourceSkillConfig {
+    readonly enabled?: boolean;
+    readonly instanceId?: string;
+    readonly pollingIntervalMs?: number;
+    readonly tags?: readonly string[];
+    /** Connector-specific options (token env names, repos, feeds, paths, …). */
+    readonly connector?: Record<string, unknown>;
+}
+/** The trusted `datasources` config section: skill name → config. */
+export type DatasourcesConfig = Readonly<Record<string, DatasourceSkillConfig | boolean>>;
+export interface BuildDatasourceSkillsResult {
+    readonly skills: readonly DatasourceSkill[];
+    /** Names that were configured but not recognized. */
+    readonly unknown: readonly string[];
+}
+/** Skill names this factory can build. */
+export declare const BUILTIN_DATASOURCE_SKILL_NAMES: readonly string[];
+/**
+ * Build datasource skills from the trusted config section. `false` or
+ * `{ enabled: false }` entries are skipped silently; unrecognized names are
+ * collected in `unknown` (never thrown) so callers can surface setup
+ * feedback without failing agent construction.
+ */
+export declare function buildDatasourceSkills(config: DatasourcesConfig | undefined, workspaceRoot?: string): BuildDatasourceSkillsResult;

package/dist/datasource/skills/gdrive/connector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Google Drive connector (issue #1301).
+ *
+ * Lists files through the Drive v3 API with a trusted, server-configured
+ * OAuth access token, exporting Google Docs/Sheets as plain text/CSV and
+ * downloading plain-text files. Binary formats are skipped. Per-file export
+ * failures degrade to warnings. Never throws; messages stay path/PII-opaque.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface GDriveConnectorOptions {
+    /** Drive v3 REST base; override to point at a mock server in tests. */
+    readonly baseUrl?: string;
+    /** OAuth access token; explicit value wins over {@link tokenEnv}. */
+    readonly token?: string;
+    /** Env var name holding the access token. Default `GDRIVE_ACCESS_TOKEN`. */
+    readonly tokenEnv?: string;
+    /** Restrict to files whose parent is this folder id. */
+    readonly folderId?: string;
+    /** Include shared-drive items in listings. */
+    readonly includeSharedDrives?: boolean;
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly maxPages?: number;
+    readonly maxDocuments?: number;
+}
+export declare class GDriveConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: GDriveConnectorOptions);
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/gdrive/index.d.ts

@@ -0,0 +1,3 @@
+export { GDriveConnector, type GDriveConnectorOptions } from "./connector.js";
+export { RcloneConnector, type RcloneConnectorOptions, type RcloneRunner, type RcloneRunResult, } from "./rclone-connector.js";
+export { GDRIVE_SKILL_DEFINITION, GDriveSkill, type GDriveSkillOptions } from "./skill.js";

package/dist/datasource/skills/gdrive/rclone-connector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Rclone-backed drive connector (issue #1301, rclone path).
+ *
+ * Uses the external `rclone` CLI (https://rclone.org) as the trusted bridge
+ * to Google Drive — or any of rclone's 70+ storage backends — so OAuth
+ * setup and token refresh live entirely in `rclone config`, not here
+ * (katok/himalaya pattern). Google Docs/Sheets are transparently exported
+ * as text via rclone's `--drive-export-formats`. Never throws; failures map
+ * onto the coarse connector failure union with path/PII-opaque messages.
+ *
+ * Listing: `rclone lsjson <remote> --recursive --files-only`
+ * Content: `rclone cat <remote>/<path>` (bounded, text formats only)
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface RcloneRunResult {
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number | null;
+}
+export type RcloneRunner = (args: readonly string[], timeoutMs: number) => Promise<RcloneRunResult>;
+export interface RcloneConnectorOptions {
+    /** Path to the rclone binary. Default bare `rclone` PATH lookup. */
+    readonly binaryPath?: string;
+    /**
+     * Rclone remote path, e.g. `gdrive:` or `gdrive:Team/Docs`. Required
+     * trusted configuration (`rclone config` defines the remote).
+     */
+    readonly remote?: string;
+    /**
+     * Indexable file extensions (lowercase, with dot). Google Docs/Sheets
+     * surface as these after `--drive-export-formats txt,csv`.
+     */
+    readonly extensions?: readonly string[];
+    /** Drive export formats forwarded to rclone. Default `txt,csv`. */
+    readonly exportFormats?: string;
+    /** Max files whose contents are fetched per run. Default 200. */
+    readonly maxDocuments?: number;
+    /** Files larger than this are skipped. Default 2 MiB. */
+    readonly maxBytesPerFile?: number;
+    /** Per-spawn timeout. Default 60s (cloud listings can be slow). */
+    readonly timeoutMs?: number;
+    /** Injectable process runner for tests. */
+    readonly runner?: RcloneRunner;
+}
+export declare class RcloneConnector implements DatasourceConnector {
+    private readonly options;
+    private readonly runner;
+    constructor(options?: RcloneConnectorOptions);
+    fetch(): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/gdrive/skill.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Google Drive datasource skill (issue #1301).
+ *
+ * Thin composition of GDriveConnector with the shared
+ * {@link ConnectorDatasourceSkill} base: descriptor, polling metadata,
+ * ok/fail indexing with path/PII-opaque diagnostics, lexical retrieval via
+ * the shared pipeline, opaque `/gdrive/<instance>/…` sources, and a
+ * progressive-disclosure agent-skill manifest.
+ */
+import type { DatasourceConnector } from "../../connector.js";
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { type GDriveConnectorOptions } from "./connector.js";
+export declare const GDRIVE_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface GDriveSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /**
+     * Trusted pre-built connector; wins over {@link connectorOptions}. Accepts
+     * any drive-backed connector (Drive REST or the rclone CLI bridge).
+     */
+    readonly connector?: DatasourceConnector;
+    readonly connectorOptions?: GDriveConnectorOptions;
+}
+export declare class GDriveSkill extends ConnectorDatasourceSkill {
+    constructor(options?: GDriveSkillOptions);
+}

package/dist/datasource/skills/github/connector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * GitHub Issues/PRs connector (issue #1303).
+ *
+ * Fetches issues and pull requests for a trusted list of `owner/repo`
+ * targets through the GitHub REST API. A token is optional (public repos
+ * work unauthenticated). Per-repo 404s degrade to warnings; 401 fails as
+ * auth and rate limiting fails the whole fetch. Never throws.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface GitHubConnectorOptions {
+    /** GitHub REST base; override to point at a mock server in tests. */
+    readonly baseUrl?: string;
+    /** Optional token; explicit value wins over {@link tokenEnv}. */
+    readonly token?: string;
+    /** Env var name holding the token. Default `GITHUB_TOKEN`. */
+    readonly tokenEnv?: string;
+    /** Repositories to index as `owner/repo`. Required trusted configuration. */
+    readonly repos?: readonly string[];
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly maxPages?: number;
+    readonly maxDocuments?: number;
+}
+export declare class GitHubConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: GitHubConnectorOptions);
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/github/index.d.ts

@@ -0,0 +1,2 @@
+export { GitHubConnector, type GitHubConnectorOptions } from "./connector.js";
+export { GITHUB_SKILL_DEFINITION, GitHubSkill, type GitHubSkillOptions } from "./skill.js";

package/dist/datasource/skills/github/skill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * GitHub Issues/PRs datasource skill (issue #1303).
+ *
+ * Thin composition of GitHubConnector with the shared
+ * {@link ConnectorDatasourceSkill} base: descriptor, polling metadata,
+ * ok/fail indexing with path/PII-opaque diagnostics, lexical retrieval via
+ * the shared pipeline, opaque `/github/<instance>/…` sources, and a
+ * progressive-disclosure agent-skill manifest.
+ */
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { GitHubConnector, type GitHubConnectorOptions } from "./connector.js";
+export declare const GITHUB_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface GitHubSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: GitHubConnector;
+    readonly connectorOptions?: GitHubConnectorOptions;
+}
+export declare class GitHubSkill extends ConnectorDatasourceSkill {
+    constructor(options?: GitHubSkillOptions);
+}

package/dist/datasource/skills/gmail/connector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Gmail connector (issue #1304).
+ *
+ * Lists and fetches messages through the Gmail REST v1 API with a trusted,
+ * server-configured OAuth access token. Per-message fetch failures degrade
+ * to warnings. Never throws; messages stay path/PII-opaque (addresses appear
+ * only inside indexed chunk content, never in diagnostics).
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface GmailConnectorOptions {
+    /** Gmail REST base; override to point at a mock server in tests. */
+    readonly baseUrl?: string;
+    /** OAuth access token; explicit value wins over {@link tokenEnv}. */
+    readonly token?: string;
+    /** Env var name holding the access token. Default `GMAIL_ACCESS_TOKEN`. */
+    readonly tokenEnv?: string;
+    /** Restrict to these label ids (e.g. `["INBOX"]`). */
+    readonly labelIds?: readonly string[];
+    /** Gmail search query (the `q` parameter). */
+    readonly query?: string;
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly maxPages?: number;
+    readonly maxDocuments?: number;
+}
+export declare class GmailConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: GmailConnectorOptions);
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+}