@treeseed/sdk 0.1.2 → 0.3.1

package/README.md

@@ -1,577 +1,168 @@
 # `@treeseed/sdk`
 
-`@treeseed/sdk` is the standalone TreeSeed SDK for content-backed and D1-backed object models.
+`@treeseed/sdk` is the main programmatic interface for Treeseed content, control-plane state, and graph-first AI context retrieval.
 
-It exposes the public model and storage surface used by TreeSeed agents and supporting tooling:
+For most consumers, the right entrypoint is `AgentSdk`.
 
-- content-backed access for pages, notes, questions, objectives, people, agents, books, and knowledge
-- D1-backed access for subscriptions, messages, agent runs, cursors, and content leases
-- stable query and mutation APIs for `get`, `read`, `search`, `follow`, `pick`, `create`, and `update`
+## Which Surface Should I Use?
 
-## Consumer Contract
+Treeseed exposes three public SDK surfaces, but they are not peers:
 
-- Node `>=20`
-- ESM package
-- install from npm as a normal package dependency
-- import from the package root or documented subpath exports
+| Surface | Role | Use It For |
+| --- | --- | --- |
+| `AgentSdk` | Primary | application code, workers, scripts, API handlers, graph-first context retrieval |
+| `ScopedAgentSdk` | Operational | agent-runtime code that must enforce model permissions and inject actor identity |
+| `ContentGraphRuntime` | Advanced | low-level graph-only integrations that want the graph engine without the rest of the SDK |
 
-Install:
+If you are unsure, use `AgentSdk`.
 
-```bash
-npm install @treeseed/sdk
-```
-
-Example:
-
-```ts
-import { AgentSdk } from '@treeseed/sdk';
-
-const sdk = new AgentSdk();
-```
+## Major Capability Groups
 
-## Using The SDK In Applications
+`AgentSdk` covers five main areas:
 
-`AgentSdk` is the main application entrypoint. It routes each request to either the content-backed store or the D1-backed store based on the model you ask for, and it always returns a JSON envelope with:
+- generic model reads and mutations across content-backed and D1-backed models
+- operational runtime state such as messages, runs, cursors, and leases
+- control-plane orchestration for work days, tasks, task events, graph runs, and reports
+- graph-first context retrieval through `parseGraphDsl()`, `resolveSeeds()`, `queryGraph()`, and `buildContextPack()`
+- agent scoping through `scopeForAgent()`
 
-- `ok`
-- `model`
-- `operation`
-- `payload`
-- optional `meta`
+## Install
 
-For most application code, the working pattern is:
+```bash
+npm install @treeseed/sdk
+```
 
-1. create one SDK instance for your process, request handler, worker, or job
-2. call `get`, `read`, `search`, `follow`, `pick`, `create`, or `update`
-3. read the typed `payload` from the returned envelope
+Consumer contract:
 
-### Initialize An SDK Instance
+- Node `>=22`
+- ESM package
+- import from the package root or documented subpath exports
 
-Use the default constructor when you want in-memory D1 behavior and a content root resolved from your environment or working directory:
+## Quickstart
 
 ```ts
 import { AgentSdk } from '@treeseed/sdk';
 
 const sdk = new AgentSdk({
-	repoRoot: '/absolute/path/to/your-site',
+  repoRoot: '/absolute/path/to/your-site',
 });
 ```
 
-Use `createLocal()` when you want a local Wrangler-backed D1 database:
+Use `AgentSdk.createLocal()` when you want a local Wrangler-backed D1 database:
 
 ```ts
 import { AgentSdk } from '@treeseed/sdk';
 
 const sdk = AgentSdk.createLocal({
-	repoRoot: '/absolute/path/to/your-site',
-	databaseName: 'treeseed-local',
-	persistTo: '.wrangler/state/v3/d1',
-});
-```
-
-Use `MemoryAgentDatabase` explicitly in tests or scripts when you want a fully in-memory setup:
-
-```ts
-import { AgentSdk } from '@treeseed/sdk';
-import { MemoryAgentDatabase } from '@treeseed/sdk/d1-store';
-
-const sdk = new AgentSdk({
-	repoRoot: '/absolute/path/to/your-site',
-	database: new MemoryAgentDatabase(),
+  repoRoot: '/absolute/path/to/your-site',
+  databaseName: 'treeseed-local',
+  persistTo: '.wrangler/state/v3/d1',
 });
 ```
 
-### Read A Single Record
-
-Use `get()` when you want one record by `id`, `slug`, or `key`.
-
-```ts
-const response = await sdk.get({
-	model: 'knowledge',
-	slug: 'guides/getting-started/1-introduction',
-});
-
-if (response.payload) {
-	console.log(response.payload.title);
-	console.log(response.payload.body);
-}
-```
-
-Use `read()` when you want the same lookup behavior but want the returned envelope to say `operation: 'read'`.
-
-```ts
-const response = await sdk.read({
-	model: 'page',
-	slug: 'getting-started',
-});
-```
+## Preferred Graph Workflow
 
-### Search Across A Model
+The preferred graph API for new integrations is:
 
-Use `search()` to list and filter records from a model.
-
-```ts
-const response = await sdk.search({
-	model: 'knowledge',
-	filters: [
-		{ field: 'title', op: 'contains', value: 'TreeSeed' },
-		{ field: 'tags', op: 'contains', value: 'onboarding' },
-	],
-	sort: [{ field: 'updated', direction: 'desc' }],
-	limit: 10,
-});
-
-console.log(response.meta?.count);
-console.log(response.payload.map((item) => item.slug));
-```
-
-`search()` is the main method for application reads such as:
-
-- listing recent notes
-- finding objectives by status
-- finding people by role or affiliation
-- finding queued D1 messages by type or status
-
-### Follow Changes Since A Timestamp
-
-Use `follow()` when your application wants records changed since a known point in time.
-
-```ts
-const response = await sdk.follow({
-	model: 'knowledge',
-	since: '2026-04-07T00:00:00.000Z',
-	filters: [{ field: 'tags', op: 'contains', value: 'treeseed' }],
-});
+1. `parseGraphDsl()`
+2. `queryGraph()`
+3. `buildContextPack()`
 
-for (const item of response.payload.items) {
-	console.log(item.slug);
-}
-```
-
-The payload shape is:
+Example:
 
 ```ts
-{
-	items: [...],
-	since: '...'
-}
-```
-
-### Pick Work Items
-
-Use `pick()` when you want the SDK to choose one item from a model for a worker.
-
-For content-backed models, `pick()` tries to claim a content lease and returns both the selected item and a `leaseToken` when a claim succeeds.
+import { AgentSdk } from '@treeseed/sdk';
 
-```ts
-const response = await sdk.pick({
-	model: 'objective',
-	workerId: 'planner-1',
-	leaseSeconds: 300,
-	filters: [{ field: 'status', op: 'eq', value: 'in progress' }],
-});
+const sdk = new AgentSdk();
+const parsed = await sdk.parseGraphDsl(
+  'ctx "queue api" for implement in /knowledge via implements,references depth 1 budget 4000 as full',
+);
 
-if (response.payload.item) {
-	console.log(response.payload.item.slug);
-	console.log(response.payload.leaseToken);
+if (!parsed.ok || !parsed.query) {
+  throw new Error(parsed.errors.join('; '));
 }
-```
-
-For `message`, `pick()` routes to queue claiming behavior in the D1 layer.
-
-### Create Content Or D1 Records
-
-Use `create()` for models that support creation.
-
-For content-backed models, pass frontmatter-like fields in `data`. The SDK writes the document and returns the created item plus git metadata.
-
-```ts
-const response = await sdk.create({
-	model: 'note',
-	actor: 'app-server',
-	data: {
-		slug: 'operating-a-small-treeseed',
-		title: 'Operating a Small TreeSeed',
-		status: 'live',
-		author: 'TreeSeed Team',
-		tags: ['operations', 'treeseed'],
-		body: 'Keep the content model simple and the workflows visible.',
-	},
-});
 
-console.log(response.payload.item.slug);
-console.log(response.payload.git);
+const graph = await sdk.queryGraph(parsed.query);
+const pack = await sdk.buildContextPack(parsed.query);
 ```
 
-For D1-backed models, `create()` delegates to the relevant store and returns the created entity.
-
-### Update Existing Records
+The public `ctx` syntax is:
 
-Use `update()` when you want to modify an existing content-backed or D1-backed record.
-
-```ts
-const response = await sdk.update({
-	model: 'objective',
-	slug: 'make-the-sample-site-easy-to-operate',
-	actor: 'app-server',
-	data: {
-		status: 'live',
-		body: 'The objective is now complete and documented.',
-	},
-});
+```text
+ctx <target>
+  [for <stage>]
+  [in <scope>]
+  [via <relation[,relation...]>]
+  [depth <0-3>]
+  [where <filter-expression>]
+  [limit <n>]
+  [budget <tokens>]
+  [as <list|brief|full|map>]
 ```
 
-For content-backed models, `update()` returns the updated item and git metadata. For D1-backed models, it returns the updated row or `null` when no matching record exists.
+The old `key=value` graph DSL is no longer supported.
 
-### Work With Messages
+## Advanced Graph Methods
 
-The SDK exposes dedicated queue helpers in addition to generic model access.
+The SDK also exposes lower-level graph primitives such as:
 
-Create a message:
+- `searchFiles()`
+- `searchSections()`
+- `searchEntities()`
+- `getGraphNode()`
+- `getNeighbors()`
+- `followReferences()`
+- `getBacklinks()`
+- `getRelated()`
+- `getSubgraph()`
+- `refreshGraph()`
 
-```ts
-const created = await sdk.createMessage({
-	type: 'guidance_ready',
-	actor: 'guide-agent',
-	payload: {
-		slug: 'guides/getting-started/1-introduction',
-	},
-	relatedModel: 'knowledge',
-	relatedId: 'guides/getting-started/1-introduction',
-	priority: 5,
-	maxAttempts: 3,
-});
-```
-
-Claim a message:
-
-```ts
-const claimed = await sdk.claimMessage({
-	workerId: 'worker-1',
-	messageTypes: ['guidance_ready'],
-	leaseSeconds: 300,
-});
-```
-
-Acknowledge a message:
-
-```ts
-await sdk.ackMessage({
-	id: 1,
-	status: 'completed',
-});
-```
-
-### Record Agent Runs, Cursors, And Leases
-
-Record a run:
+These remain public, but they are considered advanced tools. Prefer the graph-first context workflow above unless you specifically need raw lexical search or raw traversal primitives.
 
-```ts
-await sdk.recordRun({
-	run: {
-		runId: 'run-123',
-		agentSlug: 'guide-agent',
-		status: 'completed',
-		triggerSource: 'message',
-		startedAt: '2026-04-07T00:00:00.000Z',
-		finishedAt: '2026-04-07T00:05:00.000Z',
-	},
-});
-```
+## `ScopedAgentSdk`
 
-Read and update a cursor:
-
-```ts
-const cursor = await sdk.getCursor({
-	agentSlug: 'guide-agent',
-	cursorKey: 'knowledge-sync',
-});
-
-await sdk.upsertCursor({
-	agentSlug: 'guide-agent',
-	cursorKey: 'knowledge-sync',
-	cursorValue: '2026-04-07T00:00:00.000Z',
-});
-```
-
-Release one lease or all leases:
-
-```ts
-await sdk.releaseLease({
-	model: 'objective',
-	itemKey: 'make-the-sample-site-easy-to-operate',
-	leaseToken: 'lease-token',
-});
-
-await sdk.releaseAllLeases();
-```
-
-### How TreeSeed Uses Agent Runs, Cursors, And Leases
-
-These three concepts are the operational state layer for TreeSeed's agent runtime. They are not general content models like `page` or `knowledge`. Instead, they let TreeSeed coordinate ongoing agent work safely and make that work inspectable after the fact.
-
-#### Agent Runs
-
-An `agent_run` is the execution trace for one agent invocation.
-
-TreeSeed records a run when the agent kernel starts an agent, and records it again when the run finishes or fails. In practice, that means a run captures:
-
-- which agent ran
-- what triggered it
-- the current status such as `running`, `completed`, `failed`, or `waiting`
-- which message or item was selected
-- summary or error output
-- optional branch, commit, PR, and changed-path metadata
-- start and finish timestamps
-
-In the TreeSeed agent runtime, [`agent/src/agents/kernel/agent-kernel.ts`](/home/adrian/Projects/treeseed/agent/src/agents/kernel/agent-kernel.ts) calls `sdk.recordRun()` at the beginning of execution and again after the handler returns. That gives TreeSeed a durable per-run audit trail for:
-
-- debugging agent behavior
-- understanding why an agent did or did not run
-- inspecting outputs from planner, reviewer, notifier, and similar handlers
-- connecting downstream events back to the run that produced them
-
-Conceptually, `agent_run` is the answer to: "What happened during this agent invocation?"
-
-#### Agent Cursors
-
-An `agent_cursor` is a tiny per-agent checkpoint. It stores one named progress marker as:
-
-- `agentSlug`
-- `cursorKey`
-- `cursorValue`
-
-TreeSeed uses cursors to remember where an agent last left off, so the next cycle can resume from the correct point instead of starting over.
-
-In the runtime, cursors are used in a few concrete ways:
-
-- the agent kernel writes `last_run_at` after a successful run
-- follow triggers read a cursor like `follow:model-a,model-b` to know which timestamp to compare against
-- the sample planner agent writes `last_priority_run_at`
-- the sample notifier agent reads and updates `last_notified_at` so it only announces new activity
-
-You can see that usage in:
-
-- [`agent/src/agents/kernel/agent-kernel.ts`](/home/adrian/Projects/treeseed/agent/src/agents/kernel/agent-kernel.ts)
-- [`agent/src/agents/kernel/trigger-resolver.ts`](/home/adrian/Projects/treeseed/agent/src/agents/kernel/trigger-resolver.ts)
-- [`planner.ts`](/home/adrian/Projects/treeseed/core/.fixtures/treeseed-fixtures/sites/working-site/src/agents/planner.ts)
-- [`notifier.ts`](/home/adrian/Projects/treeseed/core/.fixtures/treeseed-fixtures/sites/working-site/src/agents/notifier.ts)
-
-Conceptually, `agent_cursor` is the answer to: "Where should this agent continue from next time?"
-
-#### Content Leases
-
-A `content_lease` is a short-lived claim on one content item. TreeSeed uses leases to avoid two workers picking and mutating the same item at the same time.
-
-When `pick()` runs against a content-backed model, the SDK does not just choose the "best" item. It also tries to claim a lease in the database. If another worker already holds a live lease for that item, the claim fails and the picker moves on.
-
-Each lease stores:
-
-- the model
-- the item key
-- who claimed it
-- when it was claimed
-- when the lease expires
-- a lease token
-
-This is how TreeSeed prevents duplicate work during autonomous or parallel agent execution, especially for content-backed tasks like selecting the next note, question, or objective to act on.
-
-In the SDK, the lease flow is wired through:
-
-- content selection in [`sdk/src/content-store.ts`](/home/adrian/Projects/treeseed/sdk/src/content-store.ts)
-- D1 lease persistence in [`sdk/src/stores/lease-store.ts`](/home/adrian/Projects/treeseed/sdk/src/stores/lease-store.ts)
-- runtime cleanup through `releaseLease()` and `releaseAllLeases()`
-
-The agent kernel exposes that cleanup path as `releaseLeases()` so TreeSeed operators can clear stale claims when needed.
-
-Conceptually, `content_lease` is the answer to: "Who currently owns this piece of work, and when does that claim expire?"
-
-#### How They Work Together
-
-In TreeSeed, these records solve different parts of the same runtime problem:
-
-- `agent_run` records what happened
-- `agent_cursor` records where to resume
-- `content_lease` records who currently owns a piece of work
-
-Together, they make the agent system:
-
-- inspectable, because each run leaves a trace
-- incremental, because agents can continue from saved cursors
-- concurrency-safe, because content picking is guarded by leases
-
-That combination is what lets TreeSeed move from one-off scripts toward a manageable long-running agent runtime.
-
-### Discover Agent Specs
-
-When your application stores agent definitions in content, use `listRawAgentSpecs()` or `listAgentSpecs()`.
-
-```ts
-const specs = await sdk.listAgentSpecs({ enabled: true });
-
-for (const spec of specs) {
-	console.log(spec.slug, spec.handler);
-}
-```
-
-Use `listRawAgentSpecs()` when you want the underlying content entries. Use `listAgentSpecs()` when you want normalized runtime specs.
-
-### Restrict Access With `ScopedAgentSdk`
-
-Use `scopeForAgent()` when you want application code to enforce an agent’s declared permissions before executing SDK operations.
+Use `scopeForAgent()` when code must enforce an agent’s declared permissions:
 
 ```ts
 const scoped = sdk.scopeForAgent({
-	slug: 'guide-agent',
-	permissions: [
-		{ model: 'knowledge', operations: ['get', 'read', 'search'] },
-		{ model: 'message', operations: ['create'] },
-	],
-});
-
-await scoped.search({
-	model: 'knowledge',
-	filters: [{ field: 'tags', op: 'contains', value: 'treeseed' }],
+  slug: 'guide-agent',
+  permissions: [
+    { model: 'knowledge', operations: ['get', 'read', 'search'] },
+    { model: 'message', operations: ['create'] },
+  ],
 });
 ```
 
-`ScopedAgentSdk` automatically injects the agent slug as `actor` for `create()`, `update()`, and `createMessage()`, and throws when the requested operation is not allowed.
-
-### Model And Filter Notes
-
-The SDK resolves model aliases for you. For example, `docs` maps to `knowledge` and `people` maps to `person`.
-
-Common request fields:
-
-- `model`: the canonical model or an accepted alias
-- `filters`: array of `{ field, op, value }`
-- `sort`: array of `{ field, direction }`
-- `limit`: max number of returned items
+`ScopedAgentSdk` is intended for manager/worker and agent-runtime code. It is not the default application entrypoint.
 
-Common filter operators include:
+## `ContentGraphRuntime`
 
-- `eq`
-- `in`
-- `contains`
-- `prefix`
-- `gt`
-- `gte`
-- `lt`
-- `lte`
-- `updated_since`
-- `related_to`
-
-### Envelope Pattern
-
-Every top-level SDK call returns a consistent envelope:
-
-```ts
-const response = await sdk.search({ model: 'person', limit: 1 });
-
-response.ok;        // true
-response.model;     // 'person'
-response.operation; // 'search'
-response.payload;   // typed result
-response.meta;      // optional metadata
-```
+`ContentGraphRuntime` is still exported, but it is an advanced graph runtime:
 
-That envelope shape makes it straightforward to use the SDK in API handlers, background jobs, CLIs, and agent runtimes without introducing a second application-specific response format.
+- it powers the graph subsystem behind `AgentSdk`
+- it is useful when you want only graph behavior
+- it is not the recommended starting point for most applications
 
-## Public Surface
+## Reference Docs
 
-The package root exports the main SDK class, model registry helpers, CLI option helpers, and shared SDK types.
+- [SDK Interface Reference](/home/adrian/Projects/treeseed/market/src/content/knowledge/sdk/interface-reference.mdx)
+- [Graph API Guide](/home/adrian/Projects/treeseed/market/src/content/knowledge/sdk/graph-api-guide.mdx)
+- [ctx Query Language](/home/adrian/Projects/treeseed/market/src/content/knowledge/sdk/ctx-query-language.mdx)
+- [How ctx Works](/home/adrian/Projects/treeseed/market/src/content/knowledge/sdk/ctx-query-engine.mdx)
 
-The package also exposes focused subpaths including:
+## Other Public Capabilities
 
-- `@treeseed/sdk/sdk`
-- `@treeseed/sdk/content-store`
-- `@treeseed/sdk/d1-store`
-- `@treeseed/sdk/frontmatter`
-- `@treeseed/sdk/git-runtime`
-- `@treeseed/sdk/models`
-- `@treeseed/sdk/sdk-filters`
-- `@treeseed/sdk/cli-tools`
-- `@treeseed/sdk/types`
-- `@treeseed/sdk/types/agents`
-- `@treeseed/sdk/types/cloudflare`
-- `@treeseed/sdk/wrangler-d1`
-- `@treeseed/sdk/stores/*`
+The package also exports:
 
-## Content Root Resolution
-
-Content-backed operations need a repository root that contains `src/content`.
-
-`AgentSdk` resolves that root in this order:
-
-1. the explicit `repoRoot` option
-2. `TREESEED_SDK_CONTENT_ROOT`
-3. `TREESEED_SDK_REPO_ROOT`
-4. auto-detection from the current working directory
-
-For fixture-driven development, the SDK also recognizes the shared submodule fixture at `.fixtures/treeseed-fixtures/sites/working-site`.
-
-Example with an explicit root:
-
-```ts
-import { AgentSdk } from '@treeseed/sdk';
-
-const sdk = new AgentSdk({
-	repoRoot: '/absolute/path/to/site-or-fixture-root',
-});
-```
+- workflow helpers such as `TreeseedWorkflowSdk`
+- gateway and queue clients such as `TreeseedGatewayClient` and `CloudflareQueuePullClient`
+- model registry, field, and filter utilities
+- plugin/runtime types and helpers
 
-## Local Development
-
-Initialize the shared fixtures submodule before running fixture-backed tests:
-
-```bash
-git submodule update --init --recursive
-```
+For package work:
 
 ```bash
-npm ci
+npm install
 npm run build
 npm test
-npm run test:smoke
-npm run verify
-```
-
-What each command does:
-
-- `npm run build`: builds `dist/`
-- `npm test`: runs unit tests
-- `npm run test:smoke`: packs the SDK tarball and verifies a clean import from the packed install
-- `npm run verify`: runs the release verification path used by CI
-
-## Sample Fixture Site
-
-The canonical shared fixture lives in the pinned `treeseed-fixtures` submodule at `.fixtures/treeseed-fixtures/sites/working-site`.
-
-It serves three purposes at once:
-
-- a small documentation surface about working with TreeSeed
-- the default local test ground for content-backed SDK behavior
-- a concrete example of a valid `repoRoot` for `AgentSdk`
-
-You can point the SDK at it directly:
-
-```ts
-import path from 'node:path';
-import { AgentSdk } from '@treeseed/sdk';
-
-const sdk = new AgentSdk({
-	repoRoot: path.resolve('.fixtures/treeseed-fixtures/sites/working-site'),
-});
 ```
-
-The fixture includes representative entries for pages, notes, questions, objectives, books, knowledge, people, and agents so local queries behave like a small real site instead of a synthetic stub.
-
-Shared fixture commands:
-
-```bash
-npm run fixtures:resolve
-npm run fixtures:check
-```
-
-- `fixtures:resolve`: prints the active shared fixture root
-- `fixtures:check`: verifies that the pinned shared fixture is initialized and usable

package/dist/{src/cli-tools.d.ts → cli-tools.d.ts}

@@ -1,3 +1,3 @@
-import { type AgentCliOptions } from './types/agents.ts';
+import type { AgentCliOptions } from './types/agents.ts';
 export declare function normalizeAgentCliOptions(input: unknown): AgentCliOptions;
 export declare function buildCopilotAllowToolArgs(allowTools?: AgentCliOptions['allowTools']): string[];