@getfamiliar/shared 0.1.8 → 0.1.10

package/build/AgentRun.d.ts

@@ -121,11 +121,11 @@ export interface AgentRunRow {
      */
     readonly calltype: AgentRunCallType | null;
     /**
-     * Number of retry attempts already made. Bumped each time
-     * `AgentRunner` postpones the row due to a retryable inference
-     * error. Compared against the per-handler `maxRetries` cap on
-     * each subsequent attempt; once `retry_count >= cap` the run
-     * settles `failed` instead of being postponed again.
+     * Number of retries already made. Bumped each time `AgentRunner`
+     * postpones the row due to a retryable inference error. Compared
+     * against the `maxRetries` cap (retries after the first attempt)
+     * whenever an attempt fails retryably; once `retry_count >= cap`
+     * the run settles `failed` instead of being postponed again.
      */
     readonly retryCount: number;
     /**

package/build/BastionAuth.d.ts

@@ -0,0 +1,15 @@
+/**
+ * HTTP header carrying the shared secret every bastion caller must
+ * present. The host daemon generates (or reads from `core.bastionToken`)
+ * the token at startup; the agent container receives it through its
+ * passed config, host-side CLI commands read it from
+ * `tmp/.bastion-token`. Requests without a matching header are answered
+ * with `401` before any route runs.
+ *
+ * Deliberately a custom header rather than `Authorization`: the LLM
+ * SDKs already send `Authorization` / `x-api-key` placeholders on
+ * `/llm/` that the reverse proxy replaces, and a non-simple header
+ * forces a CORS preflight the bastion never answers, which keeps
+ * browser pages on the host from reaching it.
+ */
+export declare const BASTION_TOKEN_HEADER = "x-familiar-bastion-token";

package/build/BastionAuth.js

@@ -0,0 +1,15 @@
+/**
+ * HTTP header carrying the shared secret every bastion caller must
+ * present. The host daemon generates (or reads from `core.bastionToken`)
+ * the token at startup; the agent container receives it through its
+ * passed config, host-side CLI commands read it from
+ * `tmp/.bastion-token`. Requests without a matching header are answered
+ * with `401` before any route runs.
+ *
+ * Deliberately a custom header rather than `Authorization`: the LLM
+ * SDKs already send `Authorization` / `x-api-key` placeholders on
+ * `/llm/` that the reverse proxy replaces, and a non-simple header
+ * forces a CORS preflight the bastion never answers, which keeps
+ * browser pages on the host from reaching it.
+ */
+export const BASTION_TOKEN_HEADER = "x-familiar-bastion-token";

package/build/HandlerCatalog.d.ts

@@ -18,6 +18,16 @@ export interface HandlerPath {
     /** User-facing slash form, e.g. `/chat/telegram/index`. */
     readonly slashPath: string;
 }
+/**
+ * Whether a workspace-relative path lies inside the top-level `skills/`
+ * folder. Shared by host (catalog, cron scheduler, `cron list`) and
+ * container (`HandlerFile.load`) so every side agrees that skills are
+ * never handlers.
+ *
+ * @param relativePath Workspace-relative posix path, e.g. `skills/jira-issue/SKILL.md`.
+ * @returns `true` when the first path segment is `skills`.
+ */
+export declare function isUnderSkillsFolder(relativePath: string): boolean;
 /**
  * Read-only view over the `workspace/` directory's handler files.
  *

package/build/HandlerCatalog.js

@@ -9,11 +9,24 @@ import { matchesAnyGlob } from "./PathGlob.js";
  */
 const RESERVED_ROOT_FILES = new Set(["SOUL.md", "CONTEXT.md"]);
 /**
- * Workspace subtrees that contain markdown but never handlers.
- * `skills/<name>/SKILL.md` is a shared recipe loaded via `fs_read`,
- * not an agent entry point.
+ * Top-level workspace folder holding shared recipes
+ * (`skills/<name>/SKILL.md`). Skills are pure context loaded via
+ * `fs_read`, never agent entry points — so nothing under this folder
+ * is ever listed, resolved, loaded or cron-scheduled as a handler.
  */
-const RESERVED_TOP_DIRS = new Set(["skills"]);
+const SKILLS_FOLDER = "skills";
+/**
+ * Whether a workspace-relative path lies inside the top-level `skills/`
+ * folder. Shared by host (catalog, cron scheduler, `cron list`) and
+ * container (`HandlerFile.load`) so every side agrees that skills are
+ * never handlers.
+ *
+ * @param relativePath Workspace-relative posix path, e.g. `skills/jira-issue/SKILL.md`.
+ * @returns `true` when the first path segment is `skills`.
+ */
+export function isUnderSkillsFolder(relativePath) {
+    return relativePath.split("/")[0] === SKILLS_FOLDER;
+}
 /**
  * Read-only view over the `workspace/` directory's handler files.
  *
@@ -86,6 +99,11 @@ export class HandlerCatalog {
             const relPosix = rel.split(path.sep).join("/");
             const absolute = path.join(this.workspaceDir, rel);
             if (await fileExists(absolute)) {
+                // Skills are shared recipes, never handlers — mirror the
+                // container's `HandlerFile.load` guard.
+                if (isUnderSkillsFolder(relPosix)) {
+                    return null;
+                }
                 // A file under `core.writablePaths` is never a handler, even
                 // when it exists — mirror the container's `HandlerFile.load`
                 // guard so host-side callers agree it does not resolve.
@@ -114,7 +132,7 @@ async function walkMarkdown(dir, segments, out, workspaceDir, writablePathGlobs)
     }
     for (const entry of entries) {
         if (entry.isDirectory()) {
-            if (segments.length === 0 && RESERVED_TOP_DIRS.has(entry.name)) {
+            if (segments.length === 0 && entry.name === SKILLS_FOLDER) {
                 continue;
             }
             await walkMarkdown(path.join(dir, entry.name), [...segments, entry.name], out, workspaceDir, writablePathGlobs);

package/build/index.d.ts

@@ -1,5 +1,6 @@
 export type { AgentRunCallType, AgentRunPatch, AgentRunRow, AgentRunState, NewAgentRun, } from "./AgentRun.js";
 export { AgentRunBus, type AgentRunUnsubscribe } from "./AgentRunBus.js";
+export { BASTION_TOKEN_HEADER } from "./BastionAuth.js";
 export { buildCalendarEventId, type CalendarApi, type CalendarAttachmentMeta, type CalendarAttendee, type CalendarChangePayload, type CalendarEventRow, type CalendarEventType, type CalendarImportance, type CalendarProvider, type CalendarResponseStatus, type CalendarRow, type CalendarSensitivity, type CalendarShowAs, type CalendarType, type CreateEventInput, type FindEventsQuery, type NewCalendarEvent, parseCalendarEventId, type UpdateEventInput, type UpsertCalendarInput, } from "./Calendar.js";
 export type { ChatFilter, ChatMessage, ChatRole, NewChatMessage } from "./ChatMessage.js";
 export { type ChatHandler, ChatMessageBus, type ChatUnsubscribe } from "./ChatMessageBus.js";
@@ -10,7 +11,7 @@ export type { EventFile, EventFilter, EventPatch, EventRow, EventState, NewEvent
 export { EVENT_PRIORITY } from "./Event.js";
 export { DuplicateIdempotencyKeyError, EventBus } from "./EventBus.js";
 export { estimateTokens } from "./estimateTokens.js";
-export { HandlerCatalog, type HandlerPath } from "./HandlerCatalog.js";
+export { HandlerCatalog, type HandlerPath, isUnderSkillsFolder } from "./HandlerCatalog.js";
 export type { InferenceEventRow, InferenceOutcome, NewInferenceEvent, } from "./InferenceEvent.js";
 export { InferenceEventBus } from "./InferenceEventBus.js";
 export { type CreateLoggerOptions, createLogger, jsonStdoutStream, type Logger, type LogLevel, type LogStream, prettyStdoutStream, } from "./logging/Logger.js";

package/build/index.js

@@ -1,11 +1,12 @@
 export { AgentRunBus } from "./AgentRunBus.js";
+export { BASTION_TOKEN_HEADER } from "./BastionAuth.js";
 export { buildCalendarEventId, parseCalendarEventId, } from "./Calendar.js";
 export { ChatMessageBus } from "./ChatMessageBus.js";
 export { parseCron } from "./CronExpression.js";
 export { EVENT_PRIORITY } from "./Event.js";
 export { DuplicateIdempotencyKeyError, EventBus } from "./EventBus.js";
 export { estimateTokens } from "./estimateTokens.js";
-export { HandlerCatalog } from "./HandlerCatalog.js";
+export { HandlerCatalog, isUnderSkillsFolder } from "./HandlerCatalog.js";
 export { InferenceEventBus } from "./InferenceEventBus.js";
 export { createLogger, jsonStdoutStream, prettyStdoutStream, } from "./logging/Logger.js";
 export { buildMailId, parseMailId, } from "./Mail.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getfamiliar/shared",
   "type": "module",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Familiar — shared types and bus-state client between host and container.",
   "publishConfig": {
     "access": "public"
@@ -22,7 +22,7 @@
     "build"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsc",
@@ -51,7 +51,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.12",
     "@types/luxon": "^3.7.1",
-    "@types/node": "^25.6.0",
+    "@types/node": "^22",
     "@types/pg": "^8.11.10",
     "typescript": "^6.0.3"
   },