@intent-driven-interface/backend 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +27 -0
- package/README.md +50 -2
- package/api-contracts.ts +88 -0
- package/build-tools.ts +38 -0
- package/canonicalize-pin-inputs.ts +75 -0
- package/default-agent-settings.ts +43 -0
- package/eslint.config.mjs +3 -0
- package/handle-chat-request-body.ts +52 -0
- package/idi-agent.ts +285 -0
- package/index.ts +30 -0
- package/model-message.conversion.ts +33 -0
- package/package.json +36 -4
- package/trim-messages-for-agent.ts +26 -0
- package/tsconfig.json +20 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
Server half of IDI: one LLM turn per request, wire types the frontend posts, and a host-injected persistence boundary. Tools describe UI components; they are not executed here.
|
|
2
|
+
|
|
3
|
+
## Agent skill
|
|
4
|
+
|
|
5
|
+
- Use the `intent-driven-interface` skill for IDI integration and component authoring.
|
|
6
|
+
- If the skill is not available, check the host project's `@intent-driven-interface/skill` dependency and whether `.agents/skills/intent-driven-interface/SKILL.md` (Codex) or `.claude/skills/intent-driven-interface/SKILL.md` (Claude Code) is readable.
|
|
7
|
+
- Report a missing dependency or missing/broken registration and recommend the commands in [Coding-agent setup](README.md#coding-agent-setup). Run setup from the host project, never from this dependency's directory. If already installed, only registration is needed; if `node_modules` is missing, restore dependencies first.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Core rules
|
|
11
|
+
|
|
12
|
+
- Keep tools without `execute`. Component output is user/UI state closed on the client via `closeComponent`.
|
|
13
|
+
- `./api-contracts` — wire types (`ComponentMapForBackend`, `UIMessageMetadata`, `IDIMessageWire`) safe for client imports.
|
|
14
|
+
- Inject persistence via `IDIAgent` constructor deps (`saveMessages`, `loadMessages`, `loadPinnedComponents`, `pinComponent`). Never import a database client.
|
|
15
|
+
- Optional `scheduleTask` delegates generation saves to the host. Without it, await inbound persistence and return the final save promise from stream `onEnd`.
|
|
16
|
+
- Keep wire operations `load-message-history` and `list-pinned-components` unchanged despite the callback names.
|
|
17
|
+
- Project tool results for model context with optional user input state and final component output; keep tool-call arguments and stored output unchanged.
|
|
18
|
+
- `pin-component` canonicalizes original input and optional input state before persist (sorted keys and explicit `null` preserved; schema string/number distinctions retained), then host `pinComponent`, then returns `{ pinnedComponents }` from `loadPinnedComponents` so clients replace local state from the response (no client-side merge).
|
|
19
|
+
- Trim context with `trimMessagesForAgent` before `streamText`; do not invent a separate context window.
|
|
20
|
+
- Log with `@futuristic.digital/logger`: module logger + `logger.child(getTraceContext())` per request path.
|
|
21
|
+
- Do not read `process.env` here; apps that wrap routes own env and auth.
|
|
22
|
+
|
|
23
|
+
## Boundaries
|
|
24
|
+
|
|
25
|
+
- Never import from `apps/*` or `@intent-driven-interface/frontend`.
|
|
26
|
+
- App-specific system prompts belong in `new IDIAgent({ instructions })`, not in this package's defaults beyond the shared tool-use rules.
|
|
27
|
+
- Authn/authz stays in the host app route.
|
package/README.md
CHANGED
|
@@ -1,3 +1,51 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@intent-driven-interface/backend`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Server orchestration for Intent-Driven Interface (IDI). Each request runs one AI SDK turn. Tools describe interactive components; they have no server-side `execute`. The frontend resumes the conversation after the user closes a component.
|
|
4
|
+
|
|
5
|
+
## Coding-agent setup
|
|
6
|
+
|
|
7
|
+
For coding-agent-assisted development, install and activate `@intent-driven-interface/skill`. It provides shared frontend/backend integration guidance and component-authoring rules.
|
|
8
|
+
|
|
9
|
+
Run from your application's directory containing `package.json`, not from inside `node_modules`:
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install --save-dev @intent-driven-interface/skill
|
|
13
|
+
npx @intent-driven-interface/skill add-skill --agent codex
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
For Claude Code, use `--agent claude`. If the dependency is already installed, only run `add-skill`. This creates a symlink at `.agents/skills/intent-driven-interface` (Codex) or `.claude/skills/intent-driven-interface` (Claude Code); dependency updates keep its contents current. There is no install hook. If the skill is not discovered, check that the link's `SKILL.md` is readable and restart your agent session.
|
|
17
|
+
|
|
18
|
+
## Getting started
|
|
19
|
+
|
|
20
|
+
Use Node.js 22+ and an application toolchain that supports TypeScript source exports.
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
npm install @intent-driven-interface/backend ai
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Create an `IDIAgent` with host callbacks, then pass the parsed request body and a host-resolved user ID to `agent.handleChatRequest(body, userId)`. Return its `Response` unchanged so generation can stream.
|
|
27
|
+
|
|
28
|
+
Required callbacks:
|
|
29
|
+
|
|
30
|
+
- `saveMessages({ messages, userId })`: persist message snapshots by ID.
|
|
31
|
+
- `loadMessages(userId, { beforeTimestamp?, limit? }?)`: return `{ messages, hasOlderMessages }` for a bounded history page.
|
|
32
|
+
- `loadPinnedComponents(userId)`: return the current ordered `PinnedIDIComponent[]`.
|
|
33
|
+
- `pinComponent({ userId, componentId, componentInput, componentInputState? })`: persist the original input and optional edited input independently.
|
|
34
|
+
|
|
35
|
+
Callback types are exported as `IDIAgentSaveMessages`, `IDIAgentLoadMessages`, `IDIAgentLoadPinnedComponents`, and `IDIAgentPinComponent`. Pass `instructions` to append application guidance, and optionally override `model` and `providerOptions`. The default model uses AI Gateway; the host configures provider credentials and is responsible for model usage costs.
|
|
36
|
+
|
|
37
|
+
## Persistence scheduling
|
|
38
|
+
|
|
39
|
+
By default, generation awaits the inbound message save before starting the stream and awaits the assistant save in the SDK's `onEnd` callback. Explicit `save-message` and pin operations always await persistence.
|
|
40
|
+
|
|
41
|
+
Optionally provide `scheduleTask(task: Promise<void>): void` (`IDIAgentScheduleTask`) to register generation saves with a host-managed request-lifetime scheduler. The task is already running; the host must keep it alive and handle failures. No hosting-platform dependency is required. Consume or forward the response stream for its completion callback to run.
|
|
42
|
+
|
|
43
|
+
## API and wire compatibility
|
|
44
|
+
|
|
45
|
+
- The package root exports `IDIAgent`, its options and callback types, tool builders, default settings, and context trimming.
|
|
46
|
+
- `@intent-driven-interface/backend/api-contracts` exports shared wire contracts, including `IDIMessageWire`, `ComponentMapForBackend`, and `UIMessageMetadata`.
|
|
47
|
+
- `@intent-driven-interface/backend/trim-messages-for-agent` exposes the shared 40-message context window.
|
|
48
|
+
|
|
49
|
+
The wire operations remain `generate-response`, `save-message`, `load-message-history`, `list-pinned-components`, and `pin-component`. Callback renames do not change these operation strings.
|
|
50
|
+
|
|
51
|
+
Generation receives fresh browser time and timezone through `clientTimeContext`. Model tool results expose optional `componentInputState` and final `componentOutput` without changing original invocation input or persisted messages. Pins are canonicalized before the host callback, then the current pin list is returned to replace client state.
|
package/api-contracts.ts
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { type JSONSchema7 } from 'ai';
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
/** Browser clock and timezone captured afresh for each agent generation. */
|
|
5
|
+
export const clientTimeContextSchema = z.object({
|
|
6
|
+
currentDateTime: z.iso.datetime(),
|
|
7
|
+
timeZone: z
|
|
8
|
+
.string()
|
|
9
|
+
.min(1)
|
|
10
|
+
.max(100)
|
|
11
|
+
.refine((timeZone) => {
|
|
12
|
+
try {
|
|
13
|
+
new Intl.DateTimeFormat('en-US', { timeZone });
|
|
14
|
+
return true;
|
|
15
|
+
} catch {
|
|
16
|
+
return false;
|
|
17
|
+
}
|
|
18
|
+
}, 'Expected a valid timezone'),
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
export type ClientTimeContext = z.infer<typeof clientTimeContextSchema>;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Wire-format component map sent from the frontend in the IDI backend POST body.
|
|
25
|
+
* Schemas only — no React components or functions.
|
|
26
|
+
*/
|
|
27
|
+
export type ComponentMapForBackend = Record<
|
|
28
|
+
string,
|
|
29
|
+
{
|
|
30
|
+
title?: string;
|
|
31
|
+
description?: string;
|
|
32
|
+
inputSchema: JSONSchema7;
|
|
33
|
+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
34
|
+
inputExamples?: any[];
|
|
35
|
+
outputSchema?: JSONSchema7;
|
|
36
|
+
}
|
|
37
|
+
>;
|
|
38
|
+
|
|
39
|
+
/** A pin retains invocation input independently from the user's current input state. */
|
|
40
|
+
export const componentInputSnapshotSchema = z.object({
|
|
41
|
+
componentInput: z.record(z.string(), z.unknown()),
|
|
42
|
+
componentInputState: z.record(z.string(), z.unknown()).optional(),
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
export type ComponentInputSnapshot = z.infer<
|
|
46
|
+
typeof componentInputSnapshotSchema
|
|
47
|
+
>;
|
|
48
|
+
|
|
49
|
+
/** Pins are distinct when either original input or captured input state differs. */
|
|
50
|
+
export type PinnedIDIComponent = ComponentInputSnapshot & {
|
|
51
|
+
id: string;
|
|
52
|
+
componentId: string;
|
|
53
|
+
};
|
|
54
|
+
|
|
55
|
+
/** Metadata attached to streamed IDI chat messages. */
|
|
56
|
+
export type UIMessageMetadata = {
|
|
57
|
+
/** ISO creation time; required for persistence. */
|
|
58
|
+
timestamp: string;
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
/** Wire shape for a persisted IDI chat message (JSON-safe; parts untyped). */
|
|
62
|
+
export type IDIMessageWire = {
|
|
63
|
+
id: string;
|
|
64
|
+
role: 'system' | 'user' | 'assistant';
|
|
65
|
+
metadata: UIMessageMetadata;
|
|
66
|
+
parts: unknown[];
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
/** Schema shared by storage and rendering when reading untrusted wire metadata. */
|
|
70
|
+
export const uiToolMetadataSchema = z.object({
|
|
71
|
+
componentInputState: z.json().optional(),
|
|
72
|
+
/** Draft output is discarded when the lifecycle ends. */
|
|
73
|
+
componentOutputState: z.json().optional(),
|
|
74
|
+
/** Lifecycle end time, also used to display finalized output. */
|
|
75
|
+
closedAt: z.string().optional(),
|
|
76
|
+
/** Client-only navigation/follow-up options; storage drops these. */
|
|
77
|
+
agentFollowUp: z.boolean().optional(),
|
|
78
|
+
resumeCaller: z
|
|
79
|
+
.object({
|
|
80
|
+
componentId: z.string(),
|
|
81
|
+
input: z.json(),
|
|
82
|
+
componentInputState: z.json().optional(),
|
|
83
|
+
})
|
|
84
|
+
.optional(),
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
/** Persisted UI state is separate from the model's tool input and final output. */
|
|
88
|
+
export type UIToolMetadata = z.infer<typeof uiToolMetadataSchema>;
|
package/build-tools.ts
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { jsonSchema, tool, type ToolSet, type UIMessage } from 'ai';
|
|
2
|
+
|
|
3
|
+
import { type ComponentMapForBackend } from './api-contracts';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Turns a wire-format component map into AI SDK tool schemas.
|
|
7
|
+
*
|
|
8
|
+
* These tools have no `execute` — they describe UI components the model can
|
|
9
|
+
* invoke. Results arrive later from the client via `closeComponent`.
|
|
10
|
+
*
|
|
11
|
+
* @param componentMap JSON Schema map from the frontend POST body.
|
|
12
|
+
* @returns AI SDK `ToolSet` keyed by component id.
|
|
13
|
+
*/
|
|
14
|
+
export function buildToolsFromComponentMap(
|
|
15
|
+
componentMap: ComponentMapForBackend
|
|
16
|
+
): ToolSet {
|
|
17
|
+
const tools: ToolSet = {};
|
|
18
|
+
|
|
19
|
+
for (const [componentKey, component] of Object.entries(componentMap)) {
|
|
20
|
+
tools[componentKey] = tool({
|
|
21
|
+
title: component.title,
|
|
22
|
+
description: component.description,
|
|
23
|
+
inputExamples: component.inputExamples,
|
|
24
|
+
inputSchema: jsonSchema(component.inputSchema),
|
|
25
|
+
outputSchema: component.outputSchema
|
|
26
|
+
? jsonSchema(component.outputSchema)
|
|
27
|
+
: undefined,
|
|
28
|
+
strict: true,
|
|
29
|
+
});
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
return tools;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export type IDIChatRequestBody = {
|
|
36
|
+
messages: UIMessage[];
|
|
37
|
+
componentMap: ComponentMapForBackend;
|
|
38
|
+
};
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Stable pin `inputs` for uniqueness and storage. Snapshot callers preserve
|
|
3
|
+
* value types so original inputs and editable state still match their schemas.
|
|
4
|
+
*
|
|
5
|
+
* - Object keys are sorted; `undefined` entries are omitted (not valid on the wire).
|
|
6
|
+
* - Explicit `null` is preserved — it is not the same as a missing key.
|
|
7
|
+
* - Arrays keep element order; each element is canonicalized.
|
|
8
|
+
* - Strings retain their types and exact values to match component schemas.
|
|
9
|
+
* - Non-finite numbers are dropped; `-0` becomes `0`.
|
|
10
|
+
*/
|
|
11
|
+
export const canonicalizePinInputs = (
|
|
12
|
+
inputs: Record<string, unknown>
|
|
13
|
+
): Record<string, unknown> => {
|
|
14
|
+
const canonicalized = canonicalizeValue(inputs);
|
|
15
|
+
if (
|
|
16
|
+
canonicalized !== null &&
|
|
17
|
+
typeof canonicalized === 'object' &&
|
|
18
|
+
!Array.isArray(canonicalized)
|
|
19
|
+
) {
|
|
20
|
+
return canonicalized as Record<string, unknown>;
|
|
21
|
+
}
|
|
22
|
+
return {};
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
const canonicalizeValue = (value: unknown): unknown => {
|
|
26
|
+
if (value === undefined) {
|
|
27
|
+
return undefined;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
if (value === null) {
|
|
31
|
+
return null;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
if (typeof value === 'number') {
|
|
35
|
+
if (!Number.isFinite(value)) {
|
|
36
|
+
return undefined;
|
|
37
|
+
}
|
|
38
|
+
return Object.is(value, -0) ? 0 : value;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
if (typeof value === 'string') {
|
|
42
|
+
return value;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
if (typeof value === 'boolean') {
|
|
46
|
+
return value;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
if (Array.isArray(value)) {
|
|
50
|
+
return value.map((item) => canonicalizeValue(item));
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
if (typeof value === 'object') {
|
|
54
|
+
if (value instanceof Date) {
|
|
55
|
+
return value.toISOString();
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const prototype = Object.getPrototypeOf(value);
|
|
59
|
+
if (prototype !== Object.prototype && prototype !== null) {
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
return Object.fromEntries(
|
|
64
|
+
Object.entries(value as Record<string, unknown>)
|
|
65
|
+
.map(([key, nested]) => [key, canonicalizeValue(nested)] as const)
|
|
66
|
+
.filter((entry): entry is readonly [string, unknown] => {
|
|
67
|
+
const [, nested] = entry;
|
|
68
|
+
return nested !== undefined;
|
|
69
|
+
})
|
|
70
|
+
.sort(([left], [right]) => left.localeCompare(right))
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
return undefined;
|
|
75
|
+
};
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { type LanguageModel, type streamText } from 'ai';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Settings for a single-turn IDI response generator (`streamText`).
|
|
5
|
+
* Tools have no server `execute` — results come from the client via
|
|
6
|
+
* `closeComponent`, which triggers the next request.
|
|
7
|
+
*/
|
|
8
|
+
export type IDIAgentSettings = {
|
|
9
|
+
model: LanguageModel;
|
|
10
|
+
/** Provider-specific generation controls, including reasoning effort. */
|
|
11
|
+
providerOptions?: Parameters<typeof streamText>[0]['providerOptions'];
|
|
12
|
+
/** System prompt for the model (merged with app-specific instructions). */
|
|
13
|
+
instructions: string;
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
/** Base agent configuration; apps extend with domain-specific instructions. */
|
|
17
|
+
export const defaultAgentSettings: IDIAgentSettings = {
|
|
18
|
+
// Prefer the fast variant to reduce latency when opening UI components.
|
|
19
|
+
model: 'openai/gpt-6-luna-fast',
|
|
20
|
+
// Allow lightweight reasoning to interpret component parameters while keeping responses fast.
|
|
21
|
+
providerOptions: { openai: { reasoningEffort: 'low' } },
|
|
22
|
+
|
|
23
|
+
instructions: `
|
|
24
|
+
You are a helpful assistant for building dynamic UI on-demand.
|
|
25
|
+
Your main goal is to call tools (UI components) proactively to accomplish user goals.
|
|
26
|
+
|
|
27
|
+
Whenever you call a tool (UI component), first write 1–2 short sentences explaining what you are showing and why it matches the user's request, then call the tool. Do not ask permission; do not skip this explanation.
|
|
28
|
+
Only claim what the tool can actually do given its schema; do not narrate filters, views, or ranges the parameters cannot express.
|
|
29
|
+
|
|
30
|
+
Component history:
|
|
31
|
+
- Tool-call arguments are the original parameters the model provided when opening a component.
|
|
32
|
+
- Tool results contain componentOutput (the final outcome, or null when none) and optional componentInputState (the latest parameters after user interaction).
|
|
33
|
+
- When componentInputState is present, use it to understand the user's current view or selection; do not mistake it for the original tool-call arguments.
|
|
34
|
+
|
|
35
|
+
Parameter discipline:
|
|
36
|
+
- Read every parameter name and every allowed value literally. The full name/value is the meaning (e.g. "month: next" means next month — not "next" in general).
|
|
37
|
+
- Shared words with the user request are not enough. Do not pick a value because part of it overlaps the user's wording.
|
|
38
|
+
- Tool calls use strict schemas: include every parameter; never omit a field.
|
|
39
|
+
- Use null for an unset parameter only when its schema allows null. Set a specific value only when the user's intent or conversation supports it.
|
|
40
|
+
- Follow the parameter description's stated value for unspecified input (for example, the current month). Do not ask the user to choose when null or a documented fallback applies.
|
|
41
|
+
- Ask back ONLY when a non-null value is needed, cannot be derived from the conversation, and has no documented fallback.
|
|
42
|
+
- NEVER fabricate, approximate, or guess parameter values. If unsure, use null when allowed; otherwise ask for the missing information.`,
|
|
43
|
+
};
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
clientTimeContextSchema,
|
|
5
|
+
componentInputSnapshotSchema,
|
|
6
|
+
} from './api-contracts';
|
|
7
|
+
import { type IDIAgentHandleChatRequestOptions } from './idi-agent';
|
|
8
|
+
|
|
9
|
+
const handleChatRequestBodySchema = z.discriminatedUnion('operation', [
|
|
10
|
+
z.object({
|
|
11
|
+
operation: z.literal('generate-response'),
|
|
12
|
+
messages: z.array(z.unknown()),
|
|
13
|
+
componentMap: z.unknown(),
|
|
14
|
+
clientTimeContext: clientTimeContextSchema,
|
|
15
|
+
}),
|
|
16
|
+
z.object({
|
|
17
|
+
operation: z.literal('save-message'),
|
|
18
|
+
message: z.unknown(),
|
|
19
|
+
}),
|
|
20
|
+
z.object({
|
|
21
|
+
operation: z.literal('load-message-history'),
|
|
22
|
+
beforeTimestamp: z.iso.datetime({ offset: true }).optional(),
|
|
23
|
+
}),
|
|
24
|
+
z.object({
|
|
25
|
+
operation: z.literal('list-pinned-components'),
|
|
26
|
+
}),
|
|
27
|
+
z.object({
|
|
28
|
+
operation: z.literal('pin-component'),
|
|
29
|
+
componentId: z.string().min(1),
|
|
30
|
+
...componentInputSnapshotSchema.shape,
|
|
31
|
+
}),
|
|
32
|
+
]);
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Validates the JSON body of a IDI POST before {@link IDIAgent.handleChatRequest}.
|
|
36
|
+
*/
|
|
37
|
+
export function parseHandleChatRequestBody(
|
|
38
|
+
body: unknown
|
|
39
|
+
):
|
|
40
|
+
| { success: true; data: IDIAgentHandleChatRequestOptions }
|
|
41
|
+
| { success: false } {
|
|
42
|
+
const parsed = handleChatRequestBodySchema.safeParse(body);
|
|
43
|
+
if (!parsed.success) {
|
|
44
|
+
return { success: false };
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
return {
|
|
48
|
+
success: true,
|
|
49
|
+
// @ts-expect-error Wire JSON is structurally validated; UIMessage shapes are enforced at use sites.
|
|
50
|
+
data: parsed.data,
|
|
51
|
+
};
|
|
52
|
+
}
|
package/idi-agent.ts
ADDED
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
import {
|
|
2
|
+
createLoggerForModule,
|
|
3
|
+
getTraceContext,
|
|
4
|
+
} from '@futuristic.digital/logger';
|
|
5
|
+
import {
|
|
6
|
+
createUIMessageStreamResponse,
|
|
7
|
+
generateId,
|
|
8
|
+
streamText,
|
|
9
|
+
toUIMessageStream,
|
|
10
|
+
type UIMessage,
|
|
11
|
+
} from 'ai';
|
|
12
|
+
|
|
13
|
+
import {
|
|
14
|
+
type ClientTimeContext,
|
|
15
|
+
type ComponentMapForBackend,
|
|
16
|
+
type ComponentInputSnapshot,
|
|
17
|
+
type PinnedIDIComponent,
|
|
18
|
+
type UIMessageMetadata,
|
|
19
|
+
} from './api-contracts';
|
|
20
|
+
import { buildToolsFromComponentMap } from './build-tools';
|
|
21
|
+
import { canonicalizePinInputs } from './canonicalize-pin-inputs';
|
|
22
|
+
import {
|
|
23
|
+
defaultAgentSettings,
|
|
24
|
+
type IDIAgentSettings,
|
|
25
|
+
} from './default-agent-settings';
|
|
26
|
+
import { parseHandleChatRequestBody } from './handle-chat-request-body';
|
|
27
|
+
import { convertIDIMessagesToModelMessages } from './model-message.conversion';
|
|
28
|
+
import { trimMessagesForAgent } from './trim-messages-for-agent';
|
|
29
|
+
|
|
30
|
+
const logger = createLoggerForModule(import.meta.url);
|
|
31
|
+
|
|
32
|
+
export type IDIAgentSaveMessages = (opts: {
|
|
33
|
+
messages: UIMessage[];
|
|
34
|
+
userId: string;
|
|
35
|
+
}) => Promise<void>;
|
|
36
|
+
|
|
37
|
+
export type IDIAgentLoadMessages = (
|
|
38
|
+
userId: string,
|
|
39
|
+
opts?: { beforeTimestamp?: Date; limit?: number }
|
|
40
|
+
) => Promise<{ messages: UIMessage[]; hasOlderMessages: boolean }>;
|
|
41
|
+
|
|
42
|
+
export type IDIAgentLoadPinnedComponents = (
|
|
43
|
+
userId: string
|
|
44
|
+
) => Promise<PinnedIDIComponent[]>;
|
|
45
|
+
|
|
46
|
+
export type IDIAgentPinComponent = (
|
|
47
|
+
opts: ComponentInputSnapshot & {
|
|
48
|
+
userId: string;
|
|
49
|
+
componentId: string;
|
|
50
|
+
}
|
|
51
|
+
) => Promise<void>;
|
|
52
|
+
|
|
53
|
+
/** Registers an already-started task with the host's request-lifetime scheduler. */
|
|
54
|
+
export type IDIAgentScheduleTask = (task: Promise<void>) => void;
|
|
55
|
+
|
|
56
|
+
/** App-specific overrides and host-owned persistence when constructing a {@link IDIAgent}. */
|
|
57
|
+
export type IDIAgentOptions = {
|
|
58
|
+
model?: IDIAgentSettings['model'];
|
|
59
|
+
/** Override provider controls when selecting a different model. */
|
|
60
|
+
providerOptions?: IDIAgentSettings['providerOptions'];
|
|
61
|
+
/** Appended to the shared base instructions from {@link defaultAgentSettings}. */
|
|
62
|
+
instructions?: string;
|
|
63
|
+
saveMessages: IDIAgentSaveMessages;
|
|
64
|
+
loadMessages: IDIAgentLoadMessages;
|
|
65
|
+
loadPinnedComponents: IDIAgentLoadPinnedComponents;
|
|
66
|
+
pinComponent: IDIAgentPinComponent;
|
|
67
|
+
/** Host owns task lifetime and failures; without this, generation saves are awaited. */
|
|
68
|
+
scheduleTask?: IDIAgentScheduleTask;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
export type IDIAgentHandleChatRequestOptions =
|
|
72
|
+
| {
|
|
73
|
+
operation: 'generate-response';
|
|
74
|
+
messages: UIMessage[];
|
|
75
|
+
componentMap: ComponentMapForBackend;
|
|
76
|
+
clientTimeContext: ClientTimeContext;
|
|
77
|
+
}
|
|
78
|
+
| { operation: 'save-message'; message: UIMessage }
|
|
79
|
+
| { operation: 'load-message-history'; beforeTimestamp?: string }
|
|
80
|
+
| { operation: 'list-pinned-components' }
|
|
81
|
+
| (ComponentInputSnapshot & {
|
|
82
|
+
operation: 'pin-component';
|
|
83
|
+
componentId: string;
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Configures and runs an IDI backend response generator.
|
|
88
|
+
*
|
|
89
|
+
* Each request is a single LLM turn (`streamText`). Tool results are not
|
|
90
|
+
* executed on the server — the client closes the loop when the user calls
|
|
91
|
+
* `closeComponent`, which auto-sends the next request.
|
|
92
|
+
*
|
|
93
|
+
* Merges {@link defaultAgentSettings} with app-specific options. Custom
|
|
94
|
+
* `instructions` are appended to the shared base prompt so every agent keeps
|
|
95
|
+
* the same tool-use rules. Persistence is injected by the host app.
|
|
96
|
+
*/
|
|
97
|
+
export class IDIAgent {
|
|
98
|
+
private readonly agentSettings: IDIAgentSettings;
|
|
99
|
+
private readonly saveMessages: IDIAgentSaveMessages;
|
|
100
|
+
private readonly loadMessages: IDIAgentLoadMessages;
|
|
101
|
+
private readonly loadPinnedComponents: IDIAgentLoadPinnedComponents;
|
|
102
|
+
private readonly pinComponent: IDIAgentPinComponent;
|
|
103
|
+
private readonly scheduleTask: IDIAgentScheduleTask | undefined;
|
|
104
|
+
|
|
105
|
+
constructor(options: IDIAgentOptions) {
|
|
106
|
+
const {
|
|
107
|
+
instructions: additionalInstructions,
|
|
108
|
+
saveMessages,
|
|
109
|
+
loadMessages,
|
|
110
|
+
loadPinnedComponents,
|
|
111
|
+
pinComponent,
|
|
112
|
+
scheduleTask,
|
|
113
|
+
...settingsOverrides
|
|
114
|
+
} = options;
|
|
115
|
+
|
|
116
|
+
this.saveMessages = saveMessages;
|
|
117
|
+
this.loadMessages = loadMessages;
|
|
118
|
+
this.loadPinnedComponents = loadPinnedComponents;
|
|
119
|
+
this.pinComponent = pinComponent;
|
|
120
|
+
this.scheduleTask = scheduleTask;
|
|
121
|
+
|
|
122
|
+
const defaultInstructionsTrimmed = defaultAgentSettings.instructions
|
|
123
|
+
.toString()
|
|
124
|
+
.trim();
|
|
125
|
+
const additionalInstructionsTrimmed = additionalInstructions
|
|
126
|
+
?.toString()
|
|
127
|
+
.trim();
|
|
128
|
+
const instructions =
|
|
129
|
+
defaultInstructionsTrimmed +
|
|
130
|
+
(additionalInstructionsTrimmed ? '\n\n' : '') +
|
|
131
|
+
(additionalInstructionsTrimmed ?? '');
|
|
132
|
+
|
|
133
|
+
this.agentSettings = {
|
|
134
|
+
...defaultAgentSettings,
|
|
135
|
+
...settingsOverrides,
|
|
136
|
+
instructions,
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** Keeps generation saves alive through either the host scheduler or an awaited promise. */
|
|
141
|
+
private async saveOrScheduleMessages(
|
|
142
|
+
options: Parameters<IDIAgentSaveMessages>[0]
|
|
143
|
+
): Promise<void> {
|
|
144
|
+
const task = this.saveMessages(options);
|
|
145
|
+
if (this.scheduleTask) {
|
|
146
|
+
this.scheduleTask(task);
|
|
147
|
+
} else {
|
|
148
|
+
await task;
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** Validates an IDI POST body before dispatching the operation. */
|
|
153
|
+
public async handleChatRequest(
|
|
154
|
+
body: unknown,
|
|
155
|
+
userId: string
|
|
156
|
+
): Promise<Response> {
|
|
157
|
+
const requestLogger = logger.child(getTraceContext());
|
|
158
|
+
const parsedBody = parseHandleChatRequestBody(body);
|
|
159
|
+
|
|
160
|
+
if (!parsedBody.success) {
|
|
161
|
+
requestLogger.warn('Invalid idi payload');
|
|
162
|
+
return Response.json({ error: 'Invalid payload' }, { status: 400 });
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
requestLogger.info('Handling idi request', {
|
|
166
|
+
userId,
|
|
167
|
+
operation: parsedBody.data.operation,
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
return this.handleValidChatRequest({ ...parsedBody.data, userId });
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Handles one IDI POST: generation stream, message upsert, history page,
|
|
175
|
+
* or pinned-component list/pin.
|
|
176
|
+
*/
|
|
177
|
+
private async handleValidChatRequest(
|
|
178
|
+
props: IDIAgentHandleChatRequestOptions & { userId: string }
|
|
179
|
+
): Promise<Response> {
|
|
180
|
+
const requestLogger = logger.child(getTraceContext());
|
|
181
|
+
|
|
182
|
+
if (props.operation === 'generate-response') {
|
|
183
|
+
const { messages, componentMap, userId, clientTimeContext } = props;
|
|
184
|
+
|
|
185
|
+
requestLogger.info('Generating IDI response', {
|
|
186
|
+
userId,
|
|
187
|
+
messageCount: messages.length,
|
|
188
|
+
});
|
|
189
|
+
|
|
190
|
+
// Without a host scheduler, finish the inbound save before starting the stream.
|
|
191
|
+
await this.saveOrScheduleMessages({ messages, userId });
|
|
192
|
+
const tools = buildToolsFromComponentMap(componentMap);
|
|
193
|
+
const messagesTrimmed = trimMessagesForAgent(messages);
|
|
194
|
+
// Resolve relative dates against the user's browser clock, never the server clock.
|
|
195
|
+
const userLocalDateTime = new Intl.DateTimeFormat('en-US', {
|
|
196
|
+
timeZone: clientTimeContext.timeZone,
|
|
197
|
+
dateStyle: 'full',
|
|
198
|
+
timeStyle: 'long',
|
|
199
|
+
}).format(new Date(clientTimeContext.currentDateTime));
|
|
200
|
+
|
|
201
|
+
// One LLM turn: emit text and/or tool calls, then stop; the client resumes with tool outputs.
|
|
202
|
+
const stream = streamText({
|
|
203
|
+
model: this.agentSettings.model,
|
|
204
|
+
providerOptions: this.agentSettings.providerOptions,
|
|
205
|
+
instructions: `${this.agentSettings.instructions}\n\nUser's current local time: ${userLocalDateTime} (timezone: ${clientTimeContext.timeZone}).`,
|
|
206
|
+
messages: await convertIDIMessagesToModelMessages(messagesTrimmed),
|
|
207
|
+
tools,
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
const uiMessageStream = toUIMessageStream({
|
|
211
|
+
stream: stream.stream,
|
|
212
|
+
tools,
|
|
213
|
+
// Preserve masked tool errors after AI SDK 7.0.171 changed the default.
|
|
214
|
+
redactToolErrors: true,
|
|
215
|
+
messageMetadata: ({ part }) => {
|
|
216
|
+
if (part.type === 'start') {
|
|
217
|
+
const metadata: UIMessageMetadata = {
|
|
218
|
+
timestamp: new Date().toISOString(),
|
|
219
|
+
};
|
|
220
|
+
return metadata;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
return undefined;
|
|
224
|
+
},
|
|
225
|
+
|
|
226
|
+
// Backend-generated ids are required so onEnd can upsert by messageId.
|
|
227
|
+
originalMessages: messages,
|
|
228
|
+
generateMessageId: generateId,
|
|
229
|
+
|
|
230
|
+
// Returning the promise lets the SDK await final persistence before stream closure.
|
|
231
|
+
onEnd: ({ responseMessage }) =>
|
|
232
|
+
this.saveOrScheduleMessages({ messages: [responseMessage], userId }),
|
|
233
|
+
});
|
|
234
|
+
|
|
235
|
+
return createUIMessageStreamResponse({ stream: uiMessageStream });
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
if (props.operation === 'save-message') {
|
|
239
|
+
const { message, userId } = props;
|
|
240
|
+
requestLogger.info('Saving IDI message', {
|
|
241
|
+
userId,
|
|
242
|
+
messageId: message.id,
|
|
243
|
+
});
|
|
244
|
+
await this.saveMessages({ messages: [message], userId });
|
|
245
|
+
return new Response(null, { status: 200 });
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
if (props.operation === 'load-message-history') {
|
|
249
|
+
const { beforeTimestamp, userId } = props;
|
|
250
|
+
requestLogger.info('Loading IDI message history', {
|
|
251
|
+
userId,
|
|
252
|
+
beforeTimestamp,
|
|
253
|
+
});
|
|
254
|
+
const result = await this.loadMessages(
|
|
255
|
+
userId,
|
|
256
|
+
beforeTimestamp
|
|
257
|
+
? { beforeTimestamp: new Date(beforeTimestamp) }
|
|
258
|
+
: undefined
|
|
259
|
+
);
|
|
260
|
+
return Response.json(result);
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
if (props.operation === 'list-pinned-components') {
|
|
264
|
+
const { userId } = props;
|
|
265
|
+
requestLogger.info('Listing pinned IDI components', { userId });
|
|
266
|
+
const pinnedComponents = await this.loadPinnedComponents(userId);
|
|
267
|
+
return Response.json({ pinnedComponents });
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
const { componentId, componentInput, componentInputState, userId } = props;
|
|
271
|
+
requestLogger.info('Pinning IDI component', { userId, componentId });
|
|
272
|
+
await this.pinComponent({
|
|
273
|
+
userId,
|
|
274
|
+
componentId,
|
|
275
|
+
componentInput: canonicalizePinInputs(componentInput),
|
|
276
|
+
...(componentInputState === undefined
|
|
277
|
+
? {}
|
|
278
|
+
: { componentInputState: canonicalizePinInputs(componentInputState) }),
|
|
279
|
+
});
|
|
280
|
+
// Host owns insert/conflict rules; return the authoritative list so clients
|
|
281
|
+
// do not re-implement pin merge logic.
|
|
282
|
+
const pinnedComponents = await this.loadPinnedComponents(userId);
|
|
283
|
+
return Response.json({ pinnedComponents });
|
|
284
|
+
}
|
|
285
|
+
}
|
package/index.ts
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
export {
|
|
2
|
+
type ComponentMapForBackend,
|
|
3
|
+
type PinnedIDIComponent,
|
|
4
|
+
type ComponentInputSnapshot,
|
|
5
|
+
type UIMessageMetadata,
|
|
6
|
+
type IDIMessageWire,
|
|
7
|
+
} from './api-contracts';
|
|
8
|
+
export { canonicalizePinInputs } from './canonicalize-pin-inputs';
|
|
9
|
+
export {
|
|
10
|
+
buildToolsFromComponentMap,
|
|
11
|
+
type IDIChatRequestBody,
|
|
12
|
+
} from './build-tools';
|
|
13
|
+
export {
|
|
14
|
+
defaultAgentSettings,
|
|
15
|
+
type IDIAgentSettings,
|
|
16
|
+
} from './default-agent-settings';
|
|
17
|
+
export {
|
|
18
|
+
IDIAgent,
|
|
19
|
+
type IDIAgentHandleChatRequestOptions,
|
|
20
|
+
type IDIAgentOptions,
|
|
21
|
+
type IDIAgentSaveMessages,
|
|
22
|
+
type IDIAgentScheduleTask,
|
|
23
|
+
type IDIAgentLoadMessages,
|
|
24
|
+
type IDIAgentLoadPinnedComponents,
|
|
25
|
+
type IDIAgentPinComponent,
|
|
26
|
+
} from './idi-agent';
|
|
27
|
+
export {
|
|
28
|
+
trimMessagesForAgent,
|
|
29
|
+
AGENT_CONTEXT_MAX_MESSAGES,
|
|
30
|
+
} from './trim-messages-for-agent';
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { convertToModelMessages, type UIMessage } from 'ai';
|
|
2
|
+
|
|
3
|
+
import { uiToolMetadataSchema } from './api-contracts';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Tool-call arguments retain original input. Tool results expose optional user-edited
|
|
7
|
+
* input state alongside the final outcome; UI metadata alone is invisible to the model.
|
|
8
|
+
* The projection never modifies stored messages or component output schemas.
|
|
9
|
+
*/
|
|
10
|
+
export const convertIDIMessagesToModelMessages = (messages: UIMessage[]) =>
|
|
11
|
+
convertToModelMessages(
|
|
12
|
+
messages.map((message) => ({
|
|
13
|
+
...message,
|
|
14
|
+
parts: message.parts.map((part) => {
|
|
15
|
+
if (
|
|
16
|
+
!part.type.startsWith('tool-') ||
|
|
17
|
+
!('toolCallId' in part) ||
|
|
18
|
+
part.state !== 'output-available'
|
|
19
|
+
)
|
|
20
|
+
return part;
|
|
21
|
+
const metadata = uiToolMetadataSchema.parse(part.toolMetadata ?? {});
|
|
22
|
+
return {
|
|
23
|
+
...part,
|
|
24
|
+
output: {
|
|
25
|
+
...(metadata.componentInputState === undefined
|
|
26
|
+
? {}
|
|
27
|
+
: { componentInputState: metadata.componentInputState }),
|
|
28
|
+
componentOutput: part.output ?? null,
|
|
29
|
+
},
|
|
30
|
+
};
|
|
31
|
+
}),
|
|
32
|
+
}))
|
|
33
|
+
);
|
package/package.json
CHANGED
|
@@ -1,6 +1,38 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intent-driven-interface/backend",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"publishConfig": {
|
|
6
|
+
"access": "public"
|
|
7
|
+
},
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./index.ts",
|
|
11
|
+
"default": "./index.ts"
|
|
12
|
+
},
|
|
13
|
+
"./api-contracts": {
|
|
14
|
+
"types": "./api-contracts.ts",
|
|
15
|
+
"default": "./api-contracts.ts"
|
|
16
|
+
},
|
|
17
|
+
"./trim-messages-for-agent": {
|
|
18
|
+
"types": "./trim-messages-for-agent.ts",
|
|
19
|
+
"default": "./trim-messages-for-agent.ts"
|
|
20
|
+
}
|
|
21
|
+
},
|
|
22
|
+
"scripts": {
|
|
23
|
+
"lint": "eslint .",
|
|
24
|
+
"type-check": "tsc --noEmit"
|
|
25
|
+
},
|
|
26
|
+
"engines": {
|
|
27
|
+
"node": ">=22"
|
|
28
|
+
},
|
|
29
|
+
"dependencies": {
|
|
30
|
+
"@futuristic.digital/logger": "^0.1.1",
|
|
31
|
+
"ai": "^7.0.173",
|
|
32
|
+
"zod": "^4.6.7"
|
|
33
|
+
},
|
|
34
|
+
"devDependencies": {
|
|
35
|
+
"@types/node": "^22",
|
|
36
|
+
"typescript": "^5"
|
|
37
|
+
}
|
|
38
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { type UIMessage } from 'ai';
|
|
2
|
+
|
|
3
|
+
/** Default number of recent UI messages kept in agent requests. */
|
|
4
|
+
export const AGENT_CONTEXT_MAX_MESSAGES = 40;
|
|
5
|
+
|
|
6
|
+
type MessageWithRole = Pick<UIMessage, 'role'>;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Returns the most recent chat messages that should be sent to the agent.
|
|
10
|
+
*
|
|
11
|
+
* UI state can still hold the full thread; this helper only limits what the
|
|
12
|
+
* model sees. Truncation keeps whole messages (never splits parts) by taking
|
|
13
|
+
* the last {@link AGENT_CONTEXT_MAX_MESSAGES} entries.
|
|
14
|
+
*
|
|
15
|
+
* @param messages Full thread in chronological order.
|
|
16
|
+
* @returns Either the same array, or a suffix of it when over the limit.
|
|
17
|
+
*/
|
|
18
|
+
export const trimMessagesForAgent = <M extends MessageWithRole>(
|
|
19
|
+
messages: M[]
|
|
20
|
+
): M[] => {
|
|
21
|
+
if (messages.length <= AGENT_CONTEXT_MAX_MESSAGES) {
|
|
22
|
+
return messages;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
return messages.slice(-AGENT_CONTEXT_MAX_MESSAGES);
|
|
26
|
+
};
|
package/tsconfig.json
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json.schemastore.org/tsconfig",
|
|
3
|
+
"extends": "../../tsconfig.json",
|
|
4
|
+
"compilerOptions": {
|
|
5
|
+
"target": "ES2022",
|
|
6
|
+
"lib": ["ES2022", "DOM", "DOM.Iterable"],
|
|
7
|
+
"module": "ESNext",
|
|
8
|
+
"moduleResolution": "Bundler",
|
|
9
|
+
"moduleDetection": "force",
|
|
10
|
+
"strict": true,
|
|
11
|
+
"noUncheckedIndexedAccess": true,
|
|
12
|
+
"isolatedModules": true,
|
|
13
|
+
"esModuleInterop": true,
|
|
14
|
+
"resolveJsonModule": true,
|
|
15
|
+
"skipLibCheck": true,
|
|
16
|
+
"noEmit": true
|
|
17
|
+
},
|
|
18
|
+
"include": ["**/*.ts"],
|
|
19
|
+
"exclude": ["node_modules"]
|
|
20
|
+
}
|