@getfamiliar/shared 0.1.2

package/build/MailStyleTemplate.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Per-mailbox styling commands the send path applies to every outgoing
+ * mail. Two extracted fields (signature, textStyle) plus three booleans
+ * that capture per-kind habits (whether the signature should be appended
+ * on replies / forwards, and whether the user predominantly writes
+ * plain text).
+ *
+ * Named `MailStyleTemplate` (not `MailTemplate`) because the JSON
+ * carries styling commands, not a full template body — the word
+ * "template" alone over-claims.
+ *
+ * Storage is provider-agnostic: the file lives at
+ * `data/mail/templates/<mailbox>/<name>.json` so a future Gmail / IMAP
+ * provider can write its own templates without colliding with ms365.
+ */
+export interface MailStyleTemplate {
+    /**
+     * HTML fragment — the user's signature block as Outlook stamps it
+     * onto sent mail. No `<html>`/`<head>`/`<body>` wrapper; the send
+     * path appends this verbatim at the end of the rendered body.
+     */
+    readonly signature: string;
+    /**
+     * CSS declarations the user's mails use by default, packed into a
+     * single attribute-ready string (e.g.
+     * `"font-family: Calibri; font-size: 11pt; color: #1f1f1f"`).
+     * Injected as a `style="…"` attribute on every block-level element
+     * the markdown→HTML renderer emits, since most clients ignore
+     * `<style>` blocks and require inline styling per element.
+     */
+    readonly textStyle: string;
+    /**
+     * Dominant `body.contentType` across the user's sampled Sent mails.
+     * `true` when the user predominantly writes plain text — the send
+     * path then ships new mails with `body.contentType: "Text"` and
+     * the raw markdown body (markdown reads fine as plain text).
+     */
+    readonly usePlainText: boolean;
+    /**
+     * True when the signature appears in ≥ half of the user's reply
+     * samples. Drives whether the send path appends the signature on
+     * reply paths. Empty reply bucket ⇒ `false` (no evidence; default
+     * to "don't sign").
+     */
+    readonly useSignatureOnReplies: boolean;
+    /** Same as {@link useSignatureOnReplies} for the forward bucket. */
+    readonly useSignatureOnForwards: boolean;
+}
+/** Defaults applied when a `mailstyle_update` call creates a new file. */
+export declare const MAIL_STYLE_TEMPLATE_DEFAULTS: MailStyleTemplate;
+/**
+ * Absolute path of a per-mailbox style template. `name` defaults to
+ * `"default"` — that's the single template every mailbox always has.
+ * Multi-template support (e.g. business vs. personal signature) plugs
+ * in by passing a different name; the directory layout is already
+ * forward-compatible.
+ */
+export declare function mailStyleTemplatePath(dataDir: string, mailbox: string, name?: string): string;
+/**
+ * Strip an HTML signature fragment down to a plain-text rendition the
+ * `usePlainText` new-mail branch can append below the markdown body.
+ * Three regex passes:
+ *  1. `<br>` and `</p>` / `</div>` / `</li>` close-tags become a single
+ *     newline so paragraph and list-item structure survives.
+ *  2. Every remaining tag is dropped.
+ *  3. The five common HTML entities are decoded.
+ * Trailing whitespace on each line is trimmed and runs of 3+ blank
+ * lines are collapsed to a single blank line so the result reads
+ * cleanly in a plain-text mail body.
+ */
+export declare function signatureToPlainText(html: string): string;

package/build/MailStyleTemplate.js

@@ -0,0 +1,47 @@
+import path from "node:path";
+/** Defaults applied when a `mailstyle_update` call creates a new file. */
+export const MAIL_STYLE_TEMPLATE_DEFAULTS = {
+    signature: "",
+    textStyle: "",
+    usePlainText: false,
+    useSignatureOnReplies: false,
+    useSignatureOnForwards: false,
+};
+/**
+ * Absolute path of a per-mailbox style template. `name` defaults to
+ * `"default"` — that's the single template every mailbox always has.
+ * Multi-template support (e.g. business vs. personal signature) plugs
+ * in by passing a different name; the directory layout is already
+ * forward-compatible.
+ */
+export function mailStyleTemplatePath(dataDir, mailbox, name = "default") {
+    return path.join(dataDir, "mail", "templates", mailbox, `${name}.json`);
+}
+/**
+ * Strip an HTML signature fragment down to a plain-text rendition the
+ * `usePlainText` new-mail branch can append below the markdown body.
+ * Three regex passes:
+ *  1. `<br>` and `</p>` / `</div>` / `</li>` close-tags become a single
+ *     newline so paragraph and list-item structure survives.
+ *  2. Every remaining tag is dropped.
+ *  3. The five common HTML entities are decoded.
+ * Trailing whitespace on each line is trimmed and runs of 3+ blank
+ * lines are collapsed to a single blank line so the result reads
+ * cleanly in a plain-text mail body.
+ */
+export function signatureToPlainText(html) {
+    const withBreaks = html.replace(/<br\s*\/?>/gi, "\n").replace(/<\/(p|div|li|tr)>/gi, "\n");
+    const stripped = withBreaks.replace(/<[^>]+>/g, "");
+    const decoded = stripped
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"');
+    return decoded
+        .split("\n")
+        .map((line) => line.replace(/\s+$/g, ""))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}

package/build/ModelMetaData.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Capability metadata for a single inference model, normalized across
+ * every source that can supply it (the models.dev database baked into
+ * the host, or a plugin's {@link PluginHostManifest.getModelMetaData}
+ * hook). Every field is optional because no single source fills them
+ * all — featherless, for instance, exposes no `reasoning` flag, while
+ * models.dev carries `npm` / `api` at the provider level rather than
+ * per model.
+ *
+ * The host assembles this shape and the container fetches it (through
+ * the bastion's `/model-metadata/` gateway) when an agentrun starts, so
+ * downstream code can reason about the running model's limits and
+ * capabilities.
+ */
+export interface ModelMetaData {
+    /** npm package backing the model's SDK, e.g. `@ai-sdk/openai-compatible`. */
+    npmPackage?: string;
+    /** Upstream API base URL, e.g. `https://api.featherless.ai/v1`. */
+    apiEndpoint?: string;
+    /** Whether the model supports tool / function calling. */
+    toolCall?: boolean;
+    /** Whether the model is a reasoning model. */
+    reasoning?: boolean;
+    /** Maximum context window, in tokens. */
+    contextLimit?: number;
+    /** Maximum output length, in tokens. */
+    outputLimit?: number;
+}
+/**
+ * Provider-level descriptor a plugin returns from
+ * {@link PluginHostManifest.getModelProviders} to declare an inference
+ * provider it owns (one the models.dev database doesn't cover). The host
+ * uses it to wire the reverse proxy (auth + upstream base) and the
+ * container's model factory (which `create*` to call), keyed off
+ * {@link npmPackage}.
+ */
+export interface ModelProviderDescriptor {
+    /**
+     * Provider key — the id used under `inference.apiKeys.<key>`, in
+     * `/llm/<key>/` proxy routes, and as the `model` prefix. Matches a
+     * models.dev provider id only when the plugin intentionally overrides
+     * one; otherwise it's a plugin-owned id like `featherless`.
+     */
+    readonly key: string;
+    /** npm package backing the provider's SDK, e.g. `@ai-sdk/openai-compatible`. */
+    readonly npmPackage: string;
+    /**
+     * Upstream API base URL the reverse proxy forwards to, e.g.
+     * `https://api.featherless.ai/v1`. Required for openai-compatible
+     * providers (no SDK default exists); for a provider whose npm package
+     * carries a built-in default base it may be omitted.
+     */
+    readonly apiEndpoint?: string;
+}
+/**
+ * Thrown by a {@link PluginHostManifest.getModelMetaData} hook when the
+ * plugin authoritatively owns the given provider and knows the model is
+ * not supported there. The host treats this as a definitive "no" and
+ * stops the lookup rather than consulting further plugins.
+ */
+export declare class ModelNotSupported extends Error {
+    constructor(message: string);
+}

package/build/ModelMetaData.js

@@ -0,0 +1,12 @@
+/**
+ * Thrown by a {@link PluginHostManifest.getModelMetaData} hook when the
+ * plugin authoritatively owns the given provider and knows the model is
+ * not supported there. The host treats this as a definitive "no" and
+ * stops the lookup rather than consulting further plugins.
+ */
+export class ModelNotSupported extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ModelNotSupported";
+    }
+}

package/build/PathGlob.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Root-anchored `*`-glob matcher shared across the platform: the memory
+ * indexer's exclude list, the memory context provider's embed
+ * eligibility check, the container fs tools' `core.writablePaths`
+ * allowlist, and the handler-resolution guards all speak this same
+ * grammar.
+ *
+ * `*` stands for "any characters", everything else is literal. The
+ * pattern is **anchored at the workspace root** (the leading `^`): it
+ * matches from the start of the workspace-relative POSIX path, not as a
+ * floating substring. So `wiki/**` collapses to `^wiki/.*` and matches
+ * `wiki/<rest>` only — never `notwiki/secret.md`, which the old
+ * unanchored grammar would have falsely matched. A trailing `*` (as in
+ * `wiki/**`) keeps the tail open, so the end is intentionally not
+ * anchored. Always match against the workspace-relative POSIX path so a
+ * glob means the same thing at every call site.
+ */
+export declare function matchesGlob(pattern: string, value: string): boolean;
+/** Convenience: true iff `value` matches at least one of the patterns. */
+export declare function matchesAnyGlob(patterns: readonly string[], value: string): boolean;

package/build/PathGlob.js

@@ -0,0 +1,33 @@
+/**
+ * Root-anchored `*`-glob matcher shared across the platform: the memory
+ * indexer's exclude list, the memory context provider's embed
+ * eligibility check, the container fs tools' `core.writablePaths`
+ * allowlist, and the handler-resolution guards all speak this same
+ * grammar.
+ *
+ * `*` stands for "any characters", everything else is literal. The
+ * pattern is **anchored at the workspace root** (the leading `^`): it
+ * matches from the start of the workspace-relative POSIX path, not as a
+ * floating substring. So `wiki/**` collapses to `^wiki/.*` and matches
+ * `wiki/<rest>` only — never `notwiki/secret.md`, which the old
+ * unanchored grammar would have falsely matched. A trailing `*` (as in
+ * `wiki/**`) keeps the tail open, so the end is intentionally not
+ * anchored. Always match against the workspace-relative POSIX path so a
+ * glob means the same thing at every call site.
+ */
+export function matchesGlob(pattern, value) {
+    if (pattern === "*" || pattern === "**") {
+        return true;
+    }
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}`).test(value);
+}
+/** Convenience: true iff `value` matches at least one of the patterns. */
+export function matchesAnyGlob(patterns, value) {
+    for (const pattern of patterns) {
+        if (matchesGlob(pattern, value)) {
+            return true;
+        }
+    }
+    return false;
+}