The agent framework, in lawrence-api

The module

A domain module like the others in lawrence-api/src (it mirrors how chat/ is laid out: a router.ts, sub-folders for the pieces). The split is generic framework vs. thin agent definitions.

apis/lawrence-api/src/agents/
├─ router.ts                 # POST /agents/:slug/chat — auth, principal + scope, dispatch
├─ framework/               # generic, over the AI SDK — the "BaseAgent" of the TS world
│  ├─ defineAgent.ts         #   the author API; registers a definition
│  ├─ runtime.ts             #   the loop: streamText + stopWhen, or a structured run
│  ├─ registry.ts            #   slug → AgentDefinition
│  ├─ context.ts             #   principal + scope + agentParams → initial context
│  ├─ prompt.ts              #   resolve a Langfuse prompt ref (+ label)
│  ├─ vfs/                   #   the generalised VFS — catalogue, config, generic verbs
│  │  ├─ namespaces.ts       #     ported ResourceNamespace + scope + ops + descriptions
│  │  ├─ config.ts           #     VfsConfig: namespace → allowed ops
│  │  └─ verbs.ts            #     read/list/stat/create/edit — gated, dispatch to content/vfs adapters
│  ├─ tools.ts               #   the few genuinely non-VFS tools (legal search, fill-form…)
│  ├─ output.ts              #   structured-output strategy (forced response tool / generateObject)
│  ├─ citations.ts           #   citation config + the ❬…❭ parser
│  ├─ stream.ts              #   ai-stream wire format (reuses chat/agent-mode adapters)
│  └─ types.ts               #   AgentDefinition, AgentRequest, Principal, Scope
├─ shared/
│  ├─ tools/                 # reusable non-VFS tools (legal search, fill-form…)
│  └─ schemas/               # shared zod (participant, fieldValue, citation…)
├─ matter-intake/           # a specific agent — thin
│  ├─ agent.ts               #   defineAgent({ slug, prompt, vfs, scope, principal, output })
│  └─ schemas.ts             #   matterDraft (output) + agentParams
└─ lawrence/               # (later) Lawrence re-expressed as a definition over the same framework
   └─ agent.ts

Only framework/ and shared/ are written once. Adding an agent is adding a folder with a thin agent.ts — the "delete test" of the Python plan: drop the folder and the agent cleanly disappears.

What an agent author writes

The whole of matter-intake/agent.ts. A prompt reference, a VFS config, who it runs as, and the shape it returns — nothing about the loop, streaming, auth, or wiring.

import { defineAgent, langfusePrompt } from '../framework';
import { matterDraft, matterIntakeParams } from './schemas';

export default defineAgent({
  slug:       'matter-intake',
  prompt:     langfusePrompt('matter-intake/system', { label: 'production' }), // ← Langfuse ref
  model:      'anthropic/claude-sonnet-4.6',        // routed via AI Gateway
  principals: ['admin'],                            // who may invoke it
  scope:      'firm',                                // can address firm-rooted paths; opens a matter
  params:     matterIntakeParams,                     // zod: validated agentParams
  output:     matterDraft,                            // zod → structured run → OPENING matter

  // the agent's reach is a VFS config, not bespoke tools —
  // namespace → allowed ops (a subset of what the namespace supports):
  vfs: {
    matters:  ['read', 'create'],   // firm-scoped: list / open a matter (OPENING)
    files:    ['read'],             // the uploaded intake docs
    parties:  ['read'],
    notes:    ['create'],           // the matter summary / file note
    keydates: ['create'],
    tasks:    ['create'],
  },
  // tools: []  — matter-intake needs none; other agents add tools: [legalSearch, …] for non-data actions
});

An agent is a config object, not a class. A Langfuse prompt, a VFS config (which namespaces, which ops), scope + principal, an output schema. The framework turns that into the generic VFS verbs and the loop.

What the framework owns

Why an agent definition stays that thin: everything generic lives in framework/, written once and shared by every agent. The big two — the VFS and the transports — get their own sections next.

The VFS config, generalised from matter level

Today the VFS is matter-level and all-or-nothing: every agent-visible namespace is exposed, every path rooted at a matter (documents://<matterId>/…). Generalising is two moves — make the namespace set per-agent and op-aware, and let the scope root climb above the matter.

// framework/vfs/namespaces.ts — the catalogue (ported from shared_types, + scope & ops)
export type VfsOp    = 'read' | 'list' | 'stat' | 'create' | 'edit';
export type VfsScope = 'matter' | 'firm' | 'user' | 'org' | 'jurisdiction';

export const NAMESPACES = {
  // matter-scoped — today's set
  documents: { scope: 'matter', ops: ['read','list','stat','create','edit'], desc: 'Editable Word-grade documents…' },
  files:     { scope: 'matter', ops: ['read','list','stat','edit'],          desc: 'Read-only uploaded originals…' },
  notes:     { scope: 'matter', ops: ['read','list','create','edit'],        desc: 'File notes…' },
  emails:    { scope: 'matter', ops: ['read','list','create','edit'],        desc: 'Email — drafts editable, sent read-only…' },
  tasks:     { scope: 'matter', ops: ['read','list','create'],               desc: 'To-do items…' },
  keydates:  { scope: 'matter', ops: ['read','list','create'],               desc: 'Deadlines & hearings…' },
  contacts:  { scope: 'matter', ops: ['read','list'],                        desc: 'People & companies…' },
  forms:     { scope: 'jurisdiction', ops: ['read','list'],                  desc: 'Form definitions for the jurisdiction…' },
  // …artifacts, calls, messages, quotes, feeagreements — matter-scoped, as today

  // climbing above the matter — the generalisation
  precedents:{ scope: 'firm', ops: ['read','list'],                          desc: 'Firm template library…' },
  matters:   { scope: 'firm', ops: ['read','list','create'],                 desc: 'Matters in the firm — open one (OPENING)…' }, // NEW
  threads:   { scope: 'user', ops: ['read','list'],                          desc: 'Prior AI threads for the lawyer…' },
} as const;

export type Namespace = keyof typeof NAMESPACES;

// framework/vfs/config.ts — what an agent declares
export type VfsConfig = Partial<Record<Namespace, VfsOp[]>>;  // namespace → allowed ops (⊆ NAMESPACES[ns].ops)

// validated at registration: every requested op must be supported by the namespace, and the
// agent's `scope` must permit the namespace's scope (a firm agent can't read a matter it didn't open).

The namespace vocabulary + descriptions come straight from the Python shared_types.ResourceNamespace / NAMESPACE_DESCRIPTIONS (16 namespaces); the generalisation adds a scope and an explicit ops list per namespace, the per-agent VfsConfig, and the firm-rooted matters://. Each namespace is owned by the product team that owns that domain (see Who owns what) — the catalogue is assembled from their adapters, not authored centrally.

Configuring the VFS — opt-in, or a preset to trim

A scoped agent lists what it needs; an agent like Lawrence would touch a dozen namespaces, so it starts from a preset and trims. Both are just the vfs field — it takes a plain config object or a builder.

// framework/vfs/presets.ts — every namespace of a scope, full ops; immutable + chainable
export const MATTER_VFS = preset('matter');   // documents, files, notes, emails, tasks, keydates…
export const FIRM_VFS   = preset('firm');     // matters, precedents…
export const USER_VFS   = preset('user');     // threads…

// lawrence — start from the matter preset, then refine
vfs: MATTER_VFS
      .without('quotes', 'feeagreements')        // drop namespaces it shouldn't touch
      .readonly('files', 'contacts', 'calls')    // restrict to read where it only reads
      .with(FIRM_VFS.only('precedents')),         // pull in a firm-scoped namespace

A preset is opt-out: a namespace a team later adds at that scope flows to preset users automatically — what you want for Lawrence, and exactly why scoped agents stay opt-in. The vfs field accepts either form; a builder resolves to a VfsConfig at registration.

Two transports: streaming chat, and single-shot agents

Output has two independent axes — transport (a streamed SSE turn, or one JSON response) and contract (free text, or a validated output object). They compose — which kills the old mode/surface matrix and makes utility agents trivially cheap.

// a single-shot utility agent — the cheapest definition there is
export default defineAgent({
  slug:   'title-gen',
  prompt: langfusePrompt('title-gen'),
  output: titleSchema,           // → /agents/title-gen/run returns { title }
});                              // no vfs, no tools, no thread, no stream

Who owns what

The split isn't only in the code — it's ownership. AI Engineering owns the framework; the product teams that own each domain own their slice of the VFS.

Follows the backing domain services; exact assignments to confirm with each team. The framework knows only the adapter interface — it never reaches a team's database directly. tools are owned by whoever builds them (AI Eng or a product team), the same way.

How a request flows

// framework/runtime.ts — the generic loop, in skeleton
export async function runAgent(def: AgentDefinition, req: AgentRequest) {
  const ctx     = await buildContext(def, req);        // principal/scope/params (+ initialContext)
  const system  = await resolvePrompt(def.prompt, ctx);  // Langfuse
  const tools   = resolveTools(def.vfs, def.tools, ctx); // generic VFS verbs (gated) + non-VFS tools

  if (def.output)
    return runStructured({ model: def.model, system, tools, schema: def.output, messages: req.messages });

  return streamText({ model: def.model, system, tools, messages: req.messages,
                     stopWhen: [stepCountIs(20)], onChunk: ctx.emit });
}

// framework/vfs/verbs.ts — the only VFS tools the model sees, gated by the agent's config
const vfsVerbs = (cfg: VfsConfig, ctx: AgentContext) => ({
  read:   tool({ inputSchema: z.object({ path: vfsPath }),               execute: (i) => dispatch('read',   i.path, cfg, ctx) }),
  list:   tool({ inputSchema: z.object({ path: vfsPath }),               execute: (i) => dispatch('list',   i.path, cfg, ctx) }),
  create: tool({ inputSchema: z.object({ path: vfsPath, body: z.unknown() }),  execute: (i) => dispatch('create', i.path, cfg, ctx, i.body) }),
  edit:   tool({ inputSchema: z.object({ path: vfsPath, patch: z.unknown() }), execute: (i) => dispatch('edit',   i.path, cfg, ctx, i.patch) }),
});

// dispatch(): parse <namespace>://<scopeRef>/… , assert (namespace, op) is in cfg and
// scopeRef is within the agent's scope/ACL, then call the content/vfs adapter — in-tier.
// e.g.  create matters://<firm>  { title, market, jurisdiction, participants, fields }
//        → mattersAdapter.create(…) → matterServiceClient…createMatter({ status: 'OPENING' })

Same seams as the Python plan

This isn't a new design — it's the capability-sequence BaseAgent + hooks, expressed in TS.