@truefoundry/assistant-ui-runtime 0.1.6-rc.0 → 0.1.6

package/src/plugins/truefoundry-agent-server-adapter/types.ts

@@ -0,0 +1,135 @@
+/**
+ * TrueFoundry-specific type extensions over the runtime's generic bases.
+ *
+ * The runtime defines minimal bases (SkillMount = {id,name}, McpServerMount =
+ * {id,name}, AgentSpec.config = unknown, etc.) that hosts extend via generics.
+ *
+ * This file builds the concrete TrueFoundry types by:
+ *  - Importing the runtime's AgentSpec as the base to extend.
+ *  - Importing concrete sub-types from the gateway SDK namespace rather than
+ *    re-defining them — they're purely gateway concepts.
+ *  - Composing a TfyAgentSpec that satisfies both the runtime's
+ *    `TSpec extends AgentSpec` constraint and the gateway SDK's AgentSpec shape.
+ */
+
+import type {
+    AgentSpec,
+    CreateSessionRequest,
+    ListSessionsParams,
+    Session,
+    Turn,
+    TurnState,
+} from "../../server/types.js";
+import type { TruefoundryGatewayApi } from "truefoundry-gateway-sdk";
+
+// ---------------------------------------------------------------------------
+// Re-exports — gateway sub-types surfaced for host convenience
+// ---------------------------------------------------------------------------
+
+export type TfyRuntimeConfig = TruefoundryGatewayApi.RuntimeConfig;
+export type TfyResponseFormat = TruefoundryGatewayApi.ResponseFormat;
+export type TfyModelParams = TruefoundryGatewayApi.ModelParams;
+export type TfySubject = TruefoundryGatewayApi.Subject;
+
+// ---------------------------------------------------------------------------
+// Tool selector helpers (mirrors gateway SDK enum values)
+// ---------------------------------------------------------------------------
+
+export type ToolsSelectorTag = "@all" | "@read-only";
+export type RequireApprovalToolsSelectorTag = "@all" | "@write" | "@destructive";
+export type ToolsSelectorItem = ToolsSelectorTag | string;
+export type RequireApprovalToolSelectorItem = RequireApprovalToolsSelectorTag | string;
+
+// ---------------------------------------------------------------------------
+// Runtime mount bases — derived from AgentSpec, which the runtime does export
+// (SkillMount / McpServerMount themselves are not part of its public API).
+// ---------------------------------------------------------------------------
+
+type RuntimeSkillMount = NonNullable<NonNullable<AgentSpec["skills"]>[number]>;
+type RuntimeMcpServerMount = NonNullable<NonNullable<AgentSpec["mcpServers"]>[number]>;
+
+// ---------------------------------------------------------------------------
+// Mounts — runtime base + gateway fields (fqn, type, url, tool selectors)
+// ---------------------------------------------------------------------------
+
+// Both gateway types are unions (git vs registry source, inline vs registry
+// server), so these must be intersections — an interface cannot `extends` a
+// union, and doing so silently degrades to the runtime base under skipLibCheck.
+export type TfySkillMount = RuntimeSkillMount & TruefoundryGatewayApi.SkillMount;
+
+export type TfyMcpServerMount = RuntimeMcpServerMount & TruefoundryGatewayApi.McpServer;
+
+// ---------------------------------------------------------------------------
+// AgentSpec — the concrete TrueFoundry agent definition
+// ---------------------------------------------------------------------------
+
+export interface TfyAgentSpec extends AgentSpec {
+    model: TruefoundryGatewayApi.Model;
+    skills?: TfySkillMount[];
+    mcpServers?: TfyMcpServerMount[];
+    config?: TruefoundryGatewayApi.RuntimeConfig;
+    responseFormat?: TruefoundryGatewayApi.ResponseFormat;
+    messages?: TruefoundryGatewayApi.AgentSpecUserMessage[];
+}
+
+// ---------------------------------------------------------------------------
+// Turn — runtime base narrowed to the gateway's concrete state shapes
+// ---------------------------------------------------------------------------
+
+export type TfyTurnCancelledReason = TruefoundryGatewayApi.TurnStateCancelledReason;
+export type TfyTurnStateDoneOutput = TruefoundryGatewayApi.TurnStateDoneOutput;
+
+type RuntimeTurnStateDone = Extract<TurnState, { status: "done" }>;
+type RuntimeTurnStateCancelled = Extract<TurnState, { status: "cancelled" }>;
+
+/**
+ * The runtime types `output` as `unknown` and `reason` as bare `string`. The
+ * gateway sends a model message and one of four reasons — `cancelled-for-next-turn`
+ * in particular is routine and should not render like a failure.
+ */
+export type TfyTurnState =
+    | Exclude<TurnState, { status: "done" | "cancelled" }>
+    | (Omit<RuntimeTurnStateDone, "output"> & { output?: TfyTurnStateDoneOutput })
+    | (Omit<RuntimeTurnStateCancelled, "reason"> & { reason: TfyTurnCancelledReason });
+
+export interface TfyTurn extends Turn {
+    state: TfyTurnState;
+    createdBySubject: TfySubject;
+}
+
+// ---------------------------------------------------------------------------
+// Session and request params — runtime bases + gateway-only fields
+// ---------------------------------------------------------------------------
+
+export interface TfySession<TSpec extends TfyAgentSpec = TfyAgentSpec>
+    extends Session<TSpec> {
+    createdBySubject: TfySubject;
+}
+
+export interface TfyCreateSessionRequest<TSpec extends TfyAgentSpec = TfyAgentSpec>
+    extends CreateSessionRequest<TSpec> {
+    /** Sent as `x-tfy-metadata`, persisted server-side as `request_metadata`. */
+    tfyMetadata?: string;
+}
+
+export interface TfyListSessionsParams extends ListSessionsParams {
+    /** Inclusive upper bound on `createdAt` (ISO-8601). */
+    endTimestamp?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Event-side types.
+//
+// These do NOT flow through AgentChatServer — its listEvents / listTurnEvents /
+// subscribeToTurn / prepareAndExecuteTurn signatures hardcode the runtime's
+// event types with no generic to override. Hosts narrow at the point of use
+// with the guards in `guards.ts`.
+// ---------------------------------------------------------------------------
+
+export type TfyToolInfo = TruefoundryGatewayApi.ToolInfo;
+export type TfySystemToolInfo = TruefoundryGatewayApi.TrueFoundrySystemToolInfo;
+export type TfyMcpToolInfo = TruefoundryGatewayApi.McpToolInfo;
+export type TfyModelMessageUsage = TruefoundryGatewayApi.ModelMessageUsage;
+export type TfyFinishReason = TruefoundryGatewayApi.FinishReason;
+export type TfyThreadState = TruefoundryGatewayApi.ThreadState;
+export type TfyMcpServerInitInfo = TruefoundryGatewayApi.McpServerInitInfo;

package/src/plugins/truefoundry-agent-server-adapter/types.typecheck.ts

@@ -0,0 +1,164 @@
+/**
+ * Compile-time assertions for the mount types in `types.ts`.
+ *
+ * TfySkillMount / TfyMcpServerMount are built by indexing into the runtime's
+ * exported AgentSpec. If that indexed access ever degrades to `unknown`, the
+ * intersection becomes a silent no-op and the gateway fields disappear without
+ * any error. These assertions fail `pnpm typecheck` if that happens.
+ *
+ * Not an entry point — tsup only bundles src/index.ts.
+ */
+
+import type { AgentSpec } from "../../server/types.js";
+import type { createTrueFoundryChatServer } from "./index.js";
+import type {
+    TfyAgentSpec,
+    TfyFinishReason,
+    TfyMcpServerMount,
+    TfySkillMount,
+    TfySubject,
+    TfyTurn,
+} from "./types.js";
+
+// Both gateway source variants must survive the intersection with the base.
+export const registrySkill: TfySkillMount = {
+    type: "truefoundry-skills-registry",
+    fqn: "tfy:skill:v1",
+    preload: true,
+};
+
+export const gitSkill: TfySkillMount = {
+    type: "git",
+    url: "https://github.com/acme/skills",
+    name: "reviewer",
+    ref: "main",
+};
+
+// @ts-expect-error the type discriminant must survive the intersection
+export const skillWithoutType: TfySkillMount = { fqn: "a" };
+
+// @ts-expect-error registry variant requires fqn
+export const registrySkillWithoutFqn: TfySkillMount = {
+    type: "truefoundry-skills-registry",
+};
+
+export const registeredMcp: TfyMcpServerMount = {
+    name: "github",
+    type: "truefoundry-mcp-registry",
+    enableTools: ["@read-only"],
+    requireApprovalForTools: ["@destructive"],
+};
+
+export const inlineMcp: TfyMcpServerMount = {
+    name: "custom",
+    type: "inline",
+    url: "https://example.com/mcp",
+};
+
+// @ts-expect-error the type discriminant must survive the intersection
+export const mcpWithoutType: TfyMcpServerMount = { name: "a" };
+
+// @ts-expect-error inline variant requires url
+export const inlineMcpWithoutUrl: TfyMcpServerMount = {
+    name: "a",
+    type: "inline",
+};
+
+// The gateway's own spec — a registry skill carries neither `id` nor `name` —
+// must satisfy the runtime base. A base that rejects it makes every server
+// response unassignable, which is the regression these mounts are guarding.
+declare const gatewayShapedSpec: TfyAgentSpec;
+export const asRuntimeSpec: AgentSpec = gatewayShapedSpec;
+
+// ---------------------------------------------------------------------------
+// Generic TSpec — a host extension must reach the returned server's types,
+// and the bare (defaulted) form must keep working.
+// ---------------------------------------------------------------------------
+
+interface HostSpec extends TfyAgentSpec {
+    workspaceId: string;
+}
+
+type HostServer = ReturnType<typeof createTrueFoundryChatServer<HostSpec>>;
+type DefaultServer = ReturnType<typeof createTrueFoundryChatServer>;
+
+declare const hostSession: Awaited<ReturnType<HostServer["getSession"]>>;
+declare const defaultSession: Awaited<ReturnType<DefaultServer["getSession"]>>;
+
+// Host field is visible on the spec returned by the generic server.
+export const workspaceId: string | undefined = hostSession.agentSpec?.workspaceId;
+
+// Gateway fields still flow through alongside it.
+export const hostSkills: TfySkillMount[] | undefined = hostSession.agentSpec?.skills;
+
+// @ts-expect-error the default instantiation must NOT have the host's field
+export const leakedWorkspaceId = defaultSession.agentSpec?.workspaceId;
+
+// Host spec is accepted where the server expects one.
+export declare function createHostSession(
+    server: HostServer,
+    spec: HostSpec,
+): ReturnType<HostServer["createSession"]>;
+
+// ---------------------------------------------------------------------------
+// Turn — the gateway narrowings must not collapse back into the runtime's
+// `unknown` output / bare-`string` reason.
+// ---------------------------------------------------------------------------
+
+const subject: TfySubject = {
+    subjectId: "u-1",
+    subjectType: "user",
+    subjectSlug: "someone",
+};
+
+export const cancelledTurn: TfyTurn = {
+    id: "turn-1",
+    sessionId: "session-1",
+    state: {
+        status: "cancelled",
+        reason: "cancelled-for-next-turn",
+        completedAt: "2026-01-01T00:00:00Z",
+    },
+    createdBySubject: subject,
+    createdAt: "2026-01-01T00:00:00Z",
+};
+
+export const freeformCancelReason: TfyTurn = {
+    ...cancelledTurn,
+    // @ts-expect-error reason is one of four gateway values, not any string
+    state: { status: "cancelled", reason: "nope", completedAt: "2026-01-01T00:00:00Z" },
+};
+
+// @ts-expect-error createdBySubject is required — the gateway always sends it
+export const turnWithoutSubject: TfyTurn = {
+    id: "turn-1",
+    sessionId: "session-1",
+    state: { status: "running" },
+    createdAt: "2026-01-01T00:00:00Z",
+};
+
+declare const doneTurn: Extract<TfyTurn["state"], { status: "done" }>;
+
+// `output` is the gateway's model message; on the runtime base this is `unknown`
+// and would not permit a property access at all.
+export const doneFinishReason: TfyFinishReason | null | undefined =
+    doneTurn.output?.finishReason;
+export const doneTokens: number | undefined = doneTurn.output?.usage?.inputTokens;
+
+// ---------------------------------------------------------------------------
+// Session / request params — gateway-only fields reach the server methods.
+// ---------------------------------------------------------------------------
+
+export const sessionSubject: TfySubject = hostSession.createdBySubject;
+
+export const withMetadata: Parameters<DefaultServer["createSession"]>[0] = {
+    agentName: "agent",
+    tfyMetadata: JSON.stringify({ tenant: "acme" }),
+};
+
+export const withEndTimestamp: NonNullable<
+    Parameters<DefaultServer["listSessions"]>[0]
+> = {
+    startTimestamp: "2026-01-01T00:00:00Z",
+    endTimestamp: "2026-02-01T00:00:00Z",
+};

package/src/server/types.ts

@@ -53,17 +53,23 @@ export type SearchAgentSelectorParams = {
 // Mounts — neutral SDK base (host extends with backend-specific fields)
 // ---------------------------------------------------------------------------
 
-/** Skill mount base written to AgentSpec.skills[]. Host extends for fqn, preload, etc. */
-export interface SkillMount {
-    id: string;
-    name: string;
-}
+/**
+ * Mounts written to AgentSpec.skills[] / AgentSpec.mcpServers[].
+ *
+ * These are opaque to the runtime — it stores and forwards them but never reads
+ * a field, and the backend owns the shape (the gateway identifies a skill by
+ * `fqn`, with no `id` or `name` anywhere). So the base constrains only that a
+ * mount is an object; hosts intersect their concrete mount type over it, as
+ * `TfySkillMount` / `TfyMcpServerMount` do in the gateway adapter.
+ *
+ * Naming a field here would not just be unread, it would be wrong: a base with
+ * required fields rejects the backend's own payloads, and one with only optional
+ * fields is a weak type, which TypeScript rejects for a source that shares no
+ * property with it — the gateway's registry skill shares none.
+ */
+export type SkillMount = object;
 
-/** MCP server mount base written to AgentSpec.mcpServers[]. Host extends for type, enableTools, etc. */
-export interface McpServerMount {
-    id: string;
-    name: string;
-}
+export type McpServerMount = object;
 
 // ---------------------------------------------------------------------------
 // AgentSpec — model + skills + mcpServers on base; host widens the rest