@hames-ai/connectors 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Accetto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @hames-ai/connectors
+
+The **connectors** companion package for
+[`@hames-ai/harness-patterns`](../harness-patterns/README.md): the Microsoft Graph app-side
+tools, the Neo4j non-agentic layer, and the MCP-gateway namespace catalog —
+moved out of the host app (#225 PR-3) behind injected seams. The package owns
+protocols, query shapes and schemas; the **host owns identity, tokens, content
+classification and storage**, every one of them injected.
+
+## Surface
+
+| Subpath                              | What lives there                                                                                                                                               |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.` (root barrel)                    | client-safe surface only: `mcpNamespace` / `MCP_TOOL_CATALOG`, the Neo4j→Cytoscape `transformNeo4jToCytoscape` / `parseNeo4jResults`                           |
+| `./neo4j/client`                     | `configureNeo4j({ url, user, password })` + the driver singleton — **explicit-config-only**: unset config is a named error at first use, never an env fallback |
+| `./neo4j/queries`                    | the identity-free read ops (`getSchema`, `runManualCypher`, …) — every session READ-mode (SD-14)                                                               |
+| `./neo4j/graph-edit.server`          | the intent-shaped write ops (`createGraphNode`, `linkGraphNodes`, `setGraphNodeProperty`)                                                                      |
+| `./neo4j/plain`, `./neo4j/transform` | plain projections of driver values; the Cytoscape projection                                                                                                   |
+| `./app-tools/registry`               | `createAppToolRegistry({ resolveContext })` — the generic in-process tool registry                                                                             |
+| `./mcp-catalog`                      | this deployment's tool→namespace catalog (pure data)                                                                                                           |
+| `./graph/graph-tools.server`         | `registerGraphConnectorTools(deps)` — the nine Microsoft Graph tools                                                                                           |
+| `./graph/graph-auth`                 | `GraphAuthRequiredError`, owned by the package so `instanceof` survives across the seam                                                                        |
+
+## What is injected vs imported vs composed
+
+**Injected (host → package, every field REQUIRED — a missing or non-function
+supplier throws at factory call, never degrades):**
+
+- `createAppToolRegistry({ resolveContext })`: the `userId` / `sessionId` pair
+  (the app's `getRequestUserId`/`getRequestSessionId`).
+- `registerGraphConnectorTools(deps)`:
+  - `registerAppTool` — where the tools register;
+  - `graphFetch` (S1) — delegated-token Microsoft Graph fetch; the package
+    never sees a token;
+  - `content` (S4) — `conversionEnabled` / `isConvertible` / `guessMimeType` /
+    `isTextMime`, one required supplier;
+  - `stash` — `loadStore` / `ingest`: the Data Stash bridge the file-ingest
+    tool needs (lazily resolved by the host, so composing the tools never
+    loads the storage stack).
+
+**Imported directly:** `@hames-ai/harness-patterns` (types, `assert.server`,
+`tools.server`'s `ToolsFrom` in tests) and `neo4j-driver`. Nothing else —
+there are no `app/src` imports, type-only included (pinned by the host's
+`zero-app-imports.test.ts`).
+
+**Composed host-side (not this package's business):** the `'use server'` RPC
+wrappers with their per-module auth gates (SD-13: duplicated per module, never
+imported), the transport registration on core's seam, the token/MSAL layer,
+and the doc-convert/stash modules behind the content seam. A back-edge from
+this package into the host's stash (`guessMimeType`/`isTextMime`) is
+forbidden by design — see the S4 note in the host's composition root.
+
+## No build step
+
+Like every `@hames-ai` package, this one **ships TypeScript source**: `main` and
+every code target in `exports` is a `.ts` file (`./package.json` is the one
+non-code entry), there is no `dist/`, and `pnpm pack` is the whole publish
+pipeline. Consumers are **TS-bundler consumers** — a project whose bundler or
+runtime compiles TypeScript: Vite/vinxi, esbuild, tsx, Bun. **Not**
+`node --experimental-strip-types`, which refuses to strip types under
+`node_modules` — exactly where an installed package lives
+(`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`, measured on Node v22.21.1). A
+plain `node dist/index.js` consumer is not supported either, deliberately: a
+build step would make the published artefact different from the source every
+test in this repo runs against.
+
+## Tests
+
+The suite is co-located under `__tests__/` and excluded from the published
+tarball via the `files` allowlist. Run it with `pnpm test` from
+`packages/connectors/`. It runs in a plain node environment and imports no
+host-app code; tests that need the app's request scope or its composition
+root stayed in the app's `src/__tests__/` tree.
+
+The package publishes to npm as `@hames-ai/connectors` with `publishConfig.access:
+public` (set at first publication; the setting travels with every future
+version).

package/app-tools/registry.ts

@@ -0,0 +1,185 @@
+/**
+ * App-side tool registry — Server Only.
+ *
+ * A third tool transport alongside the MCP gateway and the sandbox: tools that
+ * execute **in this process** so a credential can be resolved server-side from
+ * the authenticated user and never leave it.
+ *
+ * ## Why these can't be gateway tools
+ * The MCP gateway is a single shared-identity credential boundary (#107): every
+ * user's calls run as one principal, and the static-secret model can't inject
+ * per-user credentials. Per-user Microsoft Graph access (#110) therefore cannot
+ * go through it without giving up delegated per-user scope — the entire point.
+ *
+ * ## Identity is injected, not imported (design S3, #225 PR-3)
+ * The registry is a generic in-process registry: it resolves the caller's
+ * identity through the `resolveContext` supplier the composition root hands to
+ * `createAppToolRegistry()`, so this module carries **no host imports** —
+ * this IS the `@hames-ai/connectors` module the PR-C1 peel prepared (moved
+ * #225 PR-C2). A missing supplier throws at factory call rather than
+ * degrading (PR-2 doctrine) — a registry that silently guessed or defaulted
+ * an identity would be the one failure this module exists to prevent.
+ *
+ * ## Invariants
+ * - The schema advertised to the model has **no credential field** (#107
+ *   principle 1). The user id comes from `resolveContext` at call time, so the
+ *   model cannot choose whose data to read.
+ * - Executors receive `{ userId, sessionId }` and resolve tokens themselves; a
+ *   token must never appear in args, results, logs or the event stream.
+ * - Errors become `{ success: false, error }` rather than throwing, so one
+ *   failing tool degrades a turn instead of killing a run.
+ */
+import { assertServerOnImport } from '@hames-ai/harness-patterns/assert.server'
+import type { ToolCallResult, MCPToolDescription } from '@hames-ai/harness-patterns/types'
+
+assertServerOnImport()
+
+export interface AppToolContext {
+  /** Authenticated user id (Entra `oid`), resolved server-side. */
+  userId: string
+  /**
+   * Conversation this call belongs to, resolved server-side like `userId` — so a
+   * tool that writes into per-conversation storage (the Data Stash) cannot be
+   * pointed at someone else's conversation by the model. `null` off the request
+   * path (e.g. a background summarization); tools that need it must refuse
+   * rather than guess a session.
+   */
+  sessionId: string | null
+}
+
+export interface AppToolDefinition {
+  name: string
+  description: string
+  /** JSON Schema shown to the model. MUST NOT contain a token/credential. */
+  inputSchema: Record<string, unknown>
+  /** Namespace for `ToolSet` grouping (e.g. `graph`), mirrors MCP servers. */
+  namespace: string
+  execute: (args: Record<string, unknown>, ctx: AppToolContext) => Promise<unknown>
+}
+
+/**
+ * How the registry reads the caller's identity — injected by the composition
+ * root (`app-tools/index.server.ts`), which passes the app's
+ * `getRequestUserId`/`getRequestSessionId` pair. Same semantics as before the
+ * seam: `userId` null means no user scope, `sessionId` null means a user scope
+ * without a conversation.
+ */
+export interface AppToolResolveContext {
+  userId: () => string | null
+  sessionId: () => string | null
+}
+
+export interface AppToolRegistry {
+  /** Register an app-side tool. Later registration of the same name wins. */
+  registerAppTool(def: AppToolDefinition): void
+  /** Is this tool name handled in-process? Used by `callTool` dispatch. */
+  hasAppTool(name: string): boolean
+  /** Namespace for a registered app tool, or null when not one of ours. */
+  appToolNamespace(name: string): string | null
+  /** Advertise app tools alongside the gateway's, in the same shape. */
+  appToolDescriptions(): MCPToolDescription[]
+  /**
+   * Execute a registered app tool. Resolves the caller's user id and conversation
+   * through the injected `resolveContext` — established by
+   * `runWithRequestContext()` in both the interactive path (`runTurn`) and
+   * background runs (`runAgentInBackground`).
+   */
+  runAppTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult>
+  /** Test helper: drop all registrations. */
+  __resetAppTools(): void
+}
+
+/** Required-supplier check (PR-2 doctrine: throw, never degrade). */
+function requireSupplier<T>(bag: unknown, field: string): T {
+  const value = (bag as Record<string, unknown> | null | undefined)?.[field]
+  if (typeof value !== 'function') {
+    throw new Error(
+      `createAppToolRegistry: missing required supplier "${field}" — the registry refuses to ` +
+        "guess an identity. Pass the app's getRequestUserId/getRequestSessionId pair.",
+    )
+  }
+  return value as T
+}
+
+/**
+ * Build an app-tool registry around an injected identity resolver (design S3).
+ * The composition root calls this once and hands the resulting instance's
+ * `registerAppTool` to every tool-registration factory, so tool modules never
+ * import the registry module themselves either.
+ */
+export function createAppToolRegistry({
+  resolveContext,
+}: {
+  resolveContext: AppToolResolveContext
+}): AppToolRegistry {
+  const userId = requireSupplier<() => string | null>(resolveContext, 'userId')
+  const sessionId = requireSupplier<() => string | null>(resolveContext, 'sessionId')
+
+  const registry = new Map<string, AppToolDefinition>()
+
+  function registerAppTool(def: AppToolDefinition): void {
+    registry.set(def.name, def)
+  }
+
+  function hasAppTool(name: string): boolean {
+    return registry.has(name)
+  }
+
+  function appToolNamespace(name: string): string | null {
+    return registry.get(name)?.namespace ?? null
+  }
+
+  function appToolDescriptions(): MCPToolDescription[] {
+    return [...registry.values()].map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    }))
+  }
+
+  function __resetAppTools(): void {
+    registry.clear()
+  }
+
+  async function runAppTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult> {
+    const def = registry.get(name)
+    if (!def) {
+      return { success: false, data: null, error: `Unknown app tool: ${name}` }
+    }
+
+    const id = userId()
+    if (!id) {
+      // No user scope — e.g. a background summarization path outside
+      // runWithRequestContext. Refuse rather than guess an identity.
+      return {
+        success: false,
+        data: null,
+        error: `${name} requires an authenticated user, but no user is in scope for this call.`,
+      }
+    }
+
+    try {
+      // sessionId may legitimately be null (a user scope without a conversation);
+      // it is the tool's job to refuse if it needs one.
+      return {
+        success: true,
+        data: await def.execute(args, { userId: id, sessionId: sessionId() }),
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      // Deliberately no stack/credential detail in the tool result — it flows
+      // into the model's context and the event log.
+      console.error(`[app-tools] ${name} failed:`, message)
+      return { success: false, data: null, error: message }
+    }
+  }
+
+  return {
+    registerAppTool,
+    hasAppTool,
+    appToolNamespace,
+    appToolDescriptions,
+    runAppTool,
+    __resetAppTools,
+  }
+}

package/graph/graph-auth.ts

@@ -0,0 +1,29 @@
+/**
+ * GraphAuthRequiredError — owned by the package so `instanceof` survives the
+ * seam (#225 PR-3, design S1).
+ *
+ * Raised when we cannot get a token without user interaction — no stored cache,
+ * an unusable/expired refresh token, or a scope the user hasn't consented to.
+ * Tool wrappers translate this into a "please sign in again" result rather than
+ * failing the whole run.
+ *
+ * The class moved here VERBATIM from the host's token module in PR-C2: the
+ * host's `graphFetch` implementation keeps throwing it (importing it from
+ * here), and the Graph tools check `instanceof` — one class, two importers,
+ * so the check keeps meaning the same thing across the seam.
+ */
+export class GraphAuthRequiredError extends Error {
+  constructor(
+    message: string,
+    readonly userId: string,
+    /** HTTP status when Graph itself rejected the call (401 expired token,
+     *  403 missing consent OR resource-level denial such as SharePoint
+     *  Embedded); undefined when token ACQUISITION failed before any HTTP
+     *  request. Lets tools tell "sign in again" apart from "re-auth won't
+     *  help" (e.g. Loop content, #137). */
+    readonly status?: number,
+  ) {
+    super(message)
+    this.name = 'GraphAuthRequiredError'
+  }
+}