@asterism-app/builtin-api 0.19.1 → 0.20.0

package/README.md

@@ -10,7 +10,7 @@ General hosting facilities belong to the SDK. Built-in-specific behavior belongs
 
 ## Installation
 
-Install the testing releases with `npm install --save-dev --save-exact @asterism-app/sdk@next @asterism-app/builtin-api@next`. Declare both packages as peer dependencies with `"*"` in the plugin package.
+Install with `npm install --save-dev --save-exact @asterism-app/sdk@latest @asterism-app/builtin-api@latest` to target the stable application, or use `@next` for both to target the preview application. Declare both packages as peer dependencies with `"*"` in the plugin package.
 
 The package ships TypeScript source. Asterism supplies the built-in public API at runtime, preserving shared declaration identity. Use development versions compatible with the target application; installing these packages does not install or update the built-in implementation.
 

package/docs/agents.md

@@ -4,7 +4,7 @@ The built-in public API lets plugins interact with Asterism's existing agents th
 
 ## Declare the dependency
 
-Declare `@asterism-app/builtin-api` and `@asterism-app/sdk` in `peerDependencies` with `"*"`; the running application provides the public package instances, and the host does not gate loading on these ranges. For local development, source-package dependencies supply editor types. Import public contracts from the domain package so every participant uses the same declarations.
+Declare `@asterism-app/builtin-api` and `@asterism-app/sdk` in `peerDependencies` with `"*"`. The SDK is supplied by the host; the enabled builtin plugin provides its public API package. The host does not gate loading on dependency ranges. For local development, source-package dependencies supply editor types. Import public contracts from the domain package so every participant uses the same declarations. Disabling builtin also makes its dependent plugins unavailable.
 
 Examples are TypeScript and TSX fragments for a plugin's backend or renderer. They use public packages; install additional libraries imported by the chosen example, such as Nano ID for submission identities, in the plugin project. A plugin still supplies its manifest and composition entry points.
 
@@ -18,12 +18,28 @@ Each input submission has a submission identity, parts, a delivery mode, and a s
 
 File parts use content references with explicit read eligibility. Pass the appropriate content source with the action when forwarding files. Cancellation of the submission is separate from cancellation of the agent's independent execution, which has its own public action.
 
+## Implement communication resources
+
+Use the public Send, Peek, GetProfile, and SetProfile tool declarations when a resource provides those operations. Each resource implementation owns its addressing schema and resolves targets within its authorized scope. A shared tool name does not grant direct access to the addressed agent or its linked resources.
+
+For cross-session messaging, obtain the target session executor and submit input through the agent's public action. The public agent service supplies an agent's configured type and investigates its saved records without exposing private agent state. Obtain it from the plugin context, pass a resolved agent reference, and forward cancellation and investigation progress. Investigation captures a fresh record snapshot and does not start a turn on the target.
+
+Mesh messages retain internal sender attribution in history and project the channel name, sender name, and numeric disambiguator to the receiving model. A sender not exposed to the channel is marked as not visible. The message itself does not grant a reply route.
+
+Communication resources own their member directory and task descriptions. Resolve member names and any disambiguators against the request's captured access scope before calling agent services. Read current task descriptions when handling an operation; identity resolution and mutable profile text have separate lifetimes.
+
 ## Prepare incoming input
 
 An external preparer can inspect, replace, or reject input using the original built-in action contract. Its replacement supplies raw action input that will be parsed again. Preparation has read capabilities and does not commit session mutations.
 
 Keep a preparer's scope tied to its business purpose. It does not replace the agent implementation or acquire a private agent executor.
 
+## Prepare model requests
+
+The host collects skill packages and instruction blocks with their registering plugin's provenance. Builtin selects its effective skills and builds structured instruction blocks for each request. User skills override plugin skills, which override builtin skills.
+
+Declare an Agent preparer to filter skills or remove, change, and append instruction blocks. Preparers run synchronously in plugin initialization order. Each request captures the catalog and preparer set before awaiting linked context, then uses the prepared result for its prompt and tool batch. Removing a skill from that result also makes it unavailable to `skill_read` for that request. A catalog refresh affects later requests.
+
 ## Extend presentation
 
 Register agent UI extensions during frontend preparation and bind registration to its cancellation signal. Extensions can present controls, supplemental content, overlays, or modal interaction using the built-in presentation components.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asterism-app/builtin-api",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Public domain contracts and extensions for Asterism built-in features",
   "license": "MIT",
   "author": "Chien Zhang",
@@ -15,6 +15,12 @@
     "registry": "https://registry.npmjs.org/"
   },
   "type": "module",
+  "asterism": {
+    "manual": [
+      "docs",
+      "examples"
+    ]
+  },
   "exports": {
     "./contracts": "./src/contracts.ts",
     "./renderer": "./src/renderer.ts",
@@ -26,7 +32,9 @@
     "zod": "^4.6.5"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true }
+    "react": {
+      "optional": true
+    }
   },
   "files": [
     "src",

package/src/agent-services.ts

@@ -0,0 +1,25 @@
+import type { z } from "zod";
+import type { ResourceRef, SessionDirectory } from "@asterism-app/sdk/contracts";
+import { PluginApiError, type CallResult, type PluginContext } from "@asterism-app/sdk/runtime";
+import type { Peek, PeekResult } from "./peek.ts";
+
+/** Agent-owned operations for trusted plugins that have resolved an authorized resource reference. */
+export interface AgentServices {
+  describe(target: ResourceRef): { type: string };
+  peek(target: ResourceRef, args: z.infer<typeof Peek.argsSchema>, signal: AbortSignal,
+    publish: (data: PeekResult) => void): Promise<CallResult<PeekResult>>;
+}
+const services = new WeakMap<SessionDirectory, AgentServices>();
+
+export function registerAgentServices(plugin: PluginContext, value: AgentServices): void {
+  if (services.has(plugin.sessions)) throw new PluginApiError("conflict", "Agent services are already registered.");
+  services.set(plugin.sessions, value);
+  plugin.lifetime.signal.addEventListener("abort", () => services.delete(plugin.sessions), { once: true });
+}
+
+export function agentServices(plugin: PluginContext): AgentServices {
+  plugin.lifetime.signal.throwIfAborted();
+  const value = services.get(plugin.sessions);
+  if (!value) throw new PluginApiError("unavailable", "Agent services are unavailable.");
+  return value;
+}

package/src/agent.ts

@@ -1,4 +1,4 @@
-import { defineCreation, defineAction } from "@asterism-app/sdk/contracts";
+import { defineCreation, defineAction, defineCall } from "@asterism-app/sdk/contracts";
 import { z } from "zod";
 import { builtin } from "./identity.ts";
 import { userInputPartsSchema } from "./input.ts";
@@ -9,12 +9,14 @@ import { agentMessageSenderSchema } from "./messaging.ts";
 export const Agent = builtin.resource("agent", z.object({}));
 /** The built-in agent preset selected by default when starting from the home page. */
 export const defaultAgentPreset = "worker";
-/** The host draft target for the first submission from the home page; this is not an action routable to an existing object. */
-export const startAgentContentTarget = { contractId: builtin.name("session.start"), resourceKind: Agent.kind } as const;
 /** Pending input is delivered at request or turn boundaries; execution starts immediately when idle. */
 export const agentInputModeSchema = z.enum(["steer", "follow"]);
 /** Submissions and drafts share a 16-character Nano ID identity. */
 export const submissionIdSchema = z.string().regex(/^[A-Za-z0-9_-]{16}$/u);
+export const StartAgentSession = defineCall(builtin.name("session.start"), {
+  scope: "plugin", input: z.strictObject({ submissionId: submissionIdSchema, selection: agentSelectionSchema, parts: userInputPartsSchema }),
+  output: z.strictObject({ sessionId: z.string().min(1) }),
+});
 /** title is optional; when omitted, the creation entry point generates a random display name. */
 export const agentCreateSchema = z.strictObject({
   selection: agentSelectionSchema,

package/src/catalogs.ts

@@ -1,23 +1,12 @@
-import { z } from "zod";
-import { modelCostSchema, modelReference, resolveModelSelection, thinkingSchema } from "@asterism-app/sdk/contracts";
-import { agentSchema, type AgentSelection } from "./configuration.ts";
-import { builtin } from "./identity.ts";
+import { modelReference, resolveModelSelection, type CatalogModel, type ModelCatalogSnapshot } from "@asterism-app/sdk/contracts";
+import type { AgentConfiguration, AgentSelection, ModelRole } from "./configuration.ts";
 
-/** Catalogs projected by the application for built-in plugins; excludes configuration file formats, credentials, connection tests, and override editing state. */
-export const AgentConfigurations = builtin.data("agent.configurations", z.array(agentSchema));
-const modelProviderSchema = z.object({ id: z.string(), name: z.string(), enabled: z.boolean() });
-const modelSchema = z.object({
-  providerId: z.string(), modelId: z.string(), name: z.string(), enabled: z.boolean(),
-  contextWindow: z.number().nullable(), cost: modelCostSchema.nullable(),
-  generation: z.object({ maxOutputTokens: z.number().nullable() }),
-  capabilities: z.object({ reasoning: z.boolean(), tools: z.boolean(), thinkingLevels: z.array(thinkingSchema) }),
-});
-const roleSchema = z.object({ id: z.string(), enabled: z.boolean(), model: z.string().nullable(), thinking: thinkingSchema.nullable() });
-export const ModelConfiguration = builtin.data("model.configuration", z.object({
-  modelProviders: z.array(modelProviderSchema), models: z.array(modelSchema), roles: z.array(roleSchema), agents: z.array(agentSchema),
-}));
-export type ModelConfigurationSnapshot = z.infer<typeof ModelConfiguration.schema>;
-export type CatalogModel = z.infer<typeof modelSchema>;
+/** Builtin combines host model metadata with its own effective configuration. */
+export interface ModelConfigurationSnapshot extends ModelCatalogSnapshot {
+  roles: Pick<ModelRole, "id" | "enabled" | "model" | "thinking">[];
+  agents: AgentConfiguration[];
+}
+export type { CatalogModel } from "@asterism-app/sdk/contracts";
 
 export function resolveCatalogModel<M extends CatalogModel>(snapshot: Omit<ModelConfigurationSnapshot, "models"> & { models: M[] }, reference: string | null): M | null {
   return snapshot.models.find(model => model.enabled && modelReference(model) === reference

package/src/configuration.ts

@@ -3,6 +3,13 @@ import { modelExpressionSchema, thinkingSchema } from "@asterism-app/sdk/contrac
 const id = z.string().min(1).max(160);
 /** Configurations use readable slugs for identification by both users and models. */
 export const configurationIdSchema = z.string().trim().min(1).max(160).regex(/^[a-z0-9]+(?:[-_][a-z0-9]+)*$/u, "Use lowercase letters, digits, hyphens or underscores.");
+export const modelRoleInputSchema = z.strictObject({
+  model: modelExpressionSchema.nullable(), thinking: thinkingSchema.nullable(), enabled: z.boolean(), description: z.string().max(20_000), hidden: z.boolean(),
+});
+export const modelRoleSchema = modelRoleInputSchema.extend({ id: configurationIdSchema, builtin: z.boolean() });
+export const modelRoleOverridesSchema = modelRoleInputSchema.partial();
+export type ModelRole = z.infer<typeof modelRoleSchema>;
+export type ModelRoleOverrides = z.infer<typeof modelRoleOverridesSchema>;
 const names = z.array(id).max(200);
 const agentFieldsSchema = z.strictObject({
   enabled: z.boolean(), description: z.string().max(20_000), systemPrompt: z.string().max(100_000),

package/src/contracts.ts

@@ -1,6 +1,7 @@
 export * from "./identity.ts";
 export * from "./agent.ts";
 export * from "./messaging.ts";
+export * from "./peek.ts";
 export * from "./text.ts";
 export * from "./tools.ts";
 export * from "./search.ts";
@@ -11,3 +12,5 @@ export * from "./request-context.ts";
 export * from "./naming.ts";
 export * from "./catalogs.ts";
 export * from "./creations.ts";
+
+export type * from "./prompt.ts";

package/src/messaging.ts

@@ -9,6 +9,10 @@ export const agentMessageSenderSchema = z.discriminatedUnion("kind", [
     kind: z.literal("agent"),
     resource: z.strictObject({ sessionId: z.string().min(1), id: z.string().min(1), kind: z.string().min(1) }),
     name: z.string().min(1),
+    mesh: z.strictObject({
+      channel: z.string().min(1),
+      id: z.number().int().nonnegative().nullable(),
+    }).optional().describe("Mesh channel name and sender's numeric name disambiguator. Null means the sender is not exposed to the channel."),
   }),
 ]);
 export type AgentMessageSender = z.infer<typeof agentMessageSenderSchema>;
@@ -28,3 +32,23 @@ export const Send = defineTool({
       .describe("Message text for the recipient Agent."),
   }).describe("The message to send."),
 });
+
+export const sendResultSchema = z.strictObject({ name: z.string() })
+  .describe("Recipient Agent name for the accepted message. Processing proceeds independently.");
+export type SendResult = z.infer<typeof sendResultSchema>;
+
+export const GetProfile = defineTool({
+  id: builtin.name("tool.get_profile"), name: "get_profile",
+  description: "Read an Agent's name, configured type, and task description through a resource.",
+  guidelines: ["Null target selects your own profile on this resource. Other targets follow the resource's addressing schema."],
+  argsSchema: z.strictObject({}).describe("Empty parameter object."),
+});
+export const SetProfile = defineTool({
+  id: builtin.name("tool.set_profile"), name: "set_profile",
+  description: "Set your own task description on this resource.",
+  guidelines: ["The runtime identifies the caller. Name and configured Agent type come from the Agent.",
+    "Descriptions belong to this resource. An empty description clears your description."],
+  argsSchema: z.strictObject({
+    description: z.string().trim().max(1000).describe("A brief description of your current task. Empty text clears it."),
+  }).describe("Your task description on this resource."),
+});

package/src/naming.ts

@@ -1,23 +1,9 @@
 import { z } from "zod";
-import { defineRecord } from "@asterism-app/sdk/contracts";
 import { builtin } from "./identity.ts";
 
-/**
- * Session-level naming events: append one for each naming operation that takes effect; existing events are not rewritten.
- * Automatic naming includes the triggering message, level, and generating model; subsequent decisions read only the latest event.
- */
-export const SessionNamed = defineRecord(builtin.name("session.named"), {
-  schema: z.strictObject({
-    title: z.string().min(1).max(160),
-    source: z.enum(["user", "agent", "auto"]),
-    auto: z.strictObject({
-      level: z.enum(["initial", "refined"]),
-      messageId: z.string(),
-      model: z.string(),
-    }).optional(),
-  }).refine(data => (data.source === "auto") === (data.auto !== undefined), "Only automatic names carry naming metadata."),
-});
-
-export interface NamingApi {
-  nameByUser(sessionId: string, title: string): void;
-}
+/** Provenance attached to a host title assignment generated by the builtin paradigm. */
+export const AutomaticSessionName = builtin.data("session.automatic-name", z.strictObject({
+  level: z.enum(["initial", "refined"]),
+  messageId: z.string(),
+  model: z.string(),
+}));

package/src/peek.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { defineTool, jsonSchema, modelCompletionSchema, modelSourceSchema } from "@asterism-app/sdk/contracts";
+import { builtin } from "./identity.ts";
+
+export const Peek = defineTool({
+  id: builtin.name("tool.peek"), name: "peek",
+  description: "Investigate an Agent's saved timeline records and return a focused report using the utility model.",
+  guidelines: [
+    "target selects an Agent according to the resource implementation's schema.",
+    "question describes the information to locate and includes context for follow-up questions.",
+    "Each call reads a fresh, fixed snapshot of the selected Agent's current timeline, including records preceding context compression.",
+    "includeThinking admits saved readable thinking into the investigation; its default is false.",
+  ],
+  argsSchema: z.strictObject({
+    question: z.string().trim().min(1).describe("The question to investigate in this Agent's saved records."),
+    includeThinking: z.boolean().optional().describe("Include saved readable thinking. Defaults to false."),
+  }).describe("Question and optional access to saved readable thinking."),
+});
+export const peekResultSchema = z.strictObject({
+  snapshot: z.strictObject({ nodeId: z.string().nullable(), capturedAt: z.string(), records: z.number().int().nonnegative() }),
+  phase: z.enum(["investigating", "thinking", "searching", "reading", "writing", "done"]),
+  report: z.string(),
+  round: z.number().int().nonnegative(),
+  requests: z.array(z.strictObject({ source: modelSourceSchema.nullable(), completion: modelCompletionSchema })),
+  queries: z.array(z.strictObject({ tool: z.string(), arguments: jsonSchema, records: z.array(z.string()) })),
+}).describe("Investigation progress or report, fixed snapshot position, request measurements and retrieved record references.");
+export type PeekResult = z.infer<typeof peekResultSchema>;
+
+export function peekToModel(data: PeekResult): string {
+  return `Snapshot: ${data.snapshot.capturedAt}; timeline position: ${data.snapshot.nodeId ?? "origin"}.\n${data.report}`;
+}

package/src/preparation.ts

@@ -0,0 +1,33 @@
+import type { SessionDirectory } from "@asterism-app/sdk/contracts";
+import { defineModule, PluginApiError, type AgentSkill, type PluginContext } from "@asterism-app/sdk/runtime";
+
+import type { AgentPromptBlock } from "./prompt.ts";
+export type { AgentPromptBlock } from "./prompt.ts";
+export interface AgentPreparation {
+  skills: readonly AgentSkill[];
+  blocks: AgentPromptBlock[];
+}
+interface Preparer { id: string; prepare(value: AgentPreparation): void }
+const directories = new WeakMap<SessionDirectory, Map<string, Preparer>>();
+function entries(plugin: PluginContext) {
+  let value = directories.get(plugin.sessions);
+  if (!value) { value = new Map(); directories.set(plugin.sessions, value); }
+  return value;
+}
+/** Synchronous pure transformations run in plugin initialization order and retain entry provenance. */
+export function defineAgentPreparer(definition: Preparer) {
+  return defineModule(plugin => {
+    const registry = entries(plugin), id = `${plugin.id}:${definition.id}`;
+    if (!definition.id.trim() || registry.has(id)) throw new PluginApiError("conflict", `Duplicate or empty Agent preparer: ${id}`);
+    registry.set(id, definition);
+    plugin.lifetime.signal.addEventListener("abort", () => registry.delete(id), { once: true });
+    return {};
+  });
+}
+export function captureAgentPreparers(plugin: PluginContext) {
+  const preparers = [...entries(plugin).values()];
+  return (value: AgentPreparation): AgentPreparation => {
+    for (const preparer of preparers) preparer.prepare(value);
+    return value;
+  };
+}

package/src/prompt.ts

@@ -0,0 +1,5 @@
+export type AgentPromptBlock = (
+  | { id: string; kind: "system"; from: string; text: string }
+  | { id: string; kind: "agent"; role: string; text: string }
+  | { id: string; kind: "context"; file: string; text: string }
+) & { source: { id: string; plugin: string | null } };

package/src/runtime.ts

@@ -2,7 +2,8 @@ import { z } from "zod";
 import { belongsTo, jsonSchema, type CreationContract, type Json, type SessionDirectory } from "@asterism-app/sdk/contracts";
 import { defineModule, PluginApiError, type PluginContext, type PluginModule, type ObjectReader, type TopLevelToolContext } from "@asterism-app/sdk/runtime";
 
-export type { ManualSource } from "./manual.ts";
+export { agentServices, registerAgentServices, type AgentServices } from "./agent-services.ts";
+export { defineAgentPreparer, captureAgentPreparers, type AgentPreparation, type AgentPromptBlock } from "./preparation.ts";
 
 export interface AgentCreationDescription {
   readonly id: string;

package/src/manual.ts

@@ -1,5 +0,0 @@
-/** One directory exposed under a distinct relative path in the manual; files remain at their original location. */
-export interface ManualSource {
-  readonly path: string;
-  readonly directory: string;
-}