@finalai/agent-definition 0.1.0

package/fixtures/release-scout/agent/hooks/audit.ts

@@ -0,0 +1,24 @@
+import { defineHook } from '@finalai/agents/hooks';
+import { toolResultFrom } from '@finalai/agents/tools';
+import lookupReleaseNotes from '../tools/lookup_release_notes';
+
+export default defineHook({
+  events: {
+    async 'turn.ended'(event, ctx) {
+      if (event.data.stopReason === 'error') {
+        await ctx.final.post({ text: 'Something went wrong on my side; I have logged it.' });
+      }
+    },
+    async tool_call_update(event) {
+      const notes = toolResultFrom(event, lookupReleaseNotes);
+      if (notes?.found === false)
+        console.warn('release notes missing', { tag: event.data.rawInput['tag'] });
+    },
+    async '*'(event, ctx) {
+      await fetch('https://audit.internal/events', {
+        method: 'POST',
+        body: JSON.stringify({ id: event.meta.id, session: ctx.session.id, type: event.type }),
+      });
+    },
+  },
+});

package/fixtures/release-scout/agent/instructions/org-context.ts

@@ -0,0 +1,26 @@
+import { defineDynamic } from '@finalai/agents';
+import { defineInstructions } from '@finalai/agents/instructions';
+import * as z from 'zod';
+
+const calendarSchema = z.object({ nextRelease: z.string(), onCall: z.string() });
+
+export default defineDynamic({
+  // Only needed because the value is unknown until a session starts and Build
+  // still has to show something in this fragment's slot.
+  description: "Adds the organization's release calendar and current on-call.",
+  preview: 'Release calendar: 2.4.1 on 2026-10-10. On-call: @mina.',
+  events: {
+    'session.started': async (_event, ctx) => {
+      const url = new URL('https://ops.internal/calendar');
+      url.searchParams.set('org', ctx.session.organizationId);
+      const res = await fetch(url);
+      const text = await res.text();
+      if (!res.ok) throw new Error(`Release calendar request failed (${res.status})`);
+      const { nextRelease, onCall } = calendarSchema.parse(JSON.parse(text));
+      return defineInstructions({
+        role: 'user',
+        content: `Release calendar: ${nextRelease}. On-call: ${onCall}.`,
+      });
+    },
+  },
+});

package/fixtures/release-scout/agent/instructions.md

@@ -0,0 +1,2 @@
+You are Release Scout for the Final engineering team. Be brief. Cite release tags.
+When asked to verify something, run it rather than guessing.

package/fixtures/release-scout/agent/sandbox.ts

@@ -0,0 +1,20 @@
+import { defineSandbox } from '@finalai/agents';
+import { computerSetupGuide } from '@finalai/agents/sandboxes';
+
+// A saved guide by reference. Everything after
+// ref/version overrides the saved version's defaults.
+export const computer = computerSetupGuide({
+  ref: 'release-scout-dev',
+  version: 'latest',
+  repositories: [{ alias: 'app', repository: 'final/app', ref: 'main' }],
+  variables: ['GITHUB_TOKEN', 'NPM_TOKEN'],
+  workspace: 'session',
+  networkPolicy: 'allow-all',
+});
+
+// The default export opens the target named `computer` for each session.
+export default defineSandbox(async ({ session }) => {
+  const sandbox = await computer.open({ access: 'write' });
+  await sandbox.writeTextFile({ path: '.final/session', content: session.id });
+  return sandbox;
+});

package/fixtures/release-scout/agent/schedules/daily-digest.md

@@ -0,0 +1,7 @@
+---
+cron: '0 9 * * 1-5'
+timezone: America/Los_Angeles
+target: owner-direct
+---
+
+Summarize what shipped in the last 24 hours and anything blocking the next release.

package/fixtures/release-scout/agent/skills/triage/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: triage
+description: Triage a failing release check into a Linear issue with owner and severity.
+---
+
+1. Reproduce the failure in the computer (`shell`) before filing anything.
+2. Search Linear for an existing issue with `search_issues`.
+3. File with `create_issue` only when nothing matches; include the release tag and the failing command.

package/fixtures/release-scout/agent/skills/triage/checklist.md

@@ -0,0 +1,3 @@
+- Release tag
+- Failing command and exit code
+- First bad commit, if bisected

package/fixtures/release-scout/agent/tools/lookup_release_notes.ts

@@ -0,0 +1,24 @@
+import { defineTool } from '@finalai/agents';
+import { never } from '@finalai/agents/approval';
+import * as z from 'zod';
+
+const releaseSchema = z.object({ body: z.string().nullable(), published_at: z.string() });
+
+export default defineTool({
+  description: 'Fetch the release notes for a version tag.',
+  inputSchema: z.object({ tag: z.string().regex(/^\d+\.\d+\.\d+$/) }),
+  approval: never(),
+  async execute({ tag }, ctx) {
+    const token = await ctx.secrets.get('github-token');
+    if (token == null) throw new Error('Missing secret github-token');
+    const res = await fetch(`https://api.github.com/repos/final/app/releases/tags/v${tag}`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: ctx.abortSignal,
+    });
+    const text = await res.text();
+    if (res.status === 404) return { found: false };
+    if (!res.ok) throw new Error(`Release notes request failed (${res.status})`);
+    const { body, published_at } = releaseSchema.parse(JSON.parse(text));
+    return { found: true, publishedAt: published_at, notes: body ?? '' };
+  },
+});

package/fixtures/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {},
+  "include": ["."]
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@finalai/agent-definition",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Provider-independent agent authoring, manifest schemas, directory compiler, and harness compatibility reports.",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "fixtures",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./dist/compiler-assets/src/compiler/evaluate-child.mjs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/modules/index.d.mts",
+      "import": "./dist/modules/index.mjs",
+      "default": "./dist/modules/index.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/modules/manifest.d.mts",
+      "import": "./dist/modules/manifest.mjs",
+      "default": "./dist/modules/manifest.mjs"
+    },
+    "./authoring": {
+      "types": "./dist/modules/authoring/index.d.mts",
+      "import": "./dist/modules/authoring/index.mjs",
+      "default": "./dist/modules/authoring/index.mjs"
+    },
+    "./instructions": {
+      "types": "./dist/modules/authoring/instructions.d.mts",
+      "import": "./dist/modules/authoring/instructions.mjs",
+      "default": "./dist/modules/authoring/instructions.mjs"
+    },
+    "./approval": {
+      "types": "./dist/modules/authoring/approval.d.mts",
+      "import": "./dist/modules/authoring/approval.mjs",
+      "default": "./dist/modules/authoring/approval.mjs"
+    },
+    "./hooks": {
+      "types": "./dist/modules/authoring/hooks.d.mts",
+      "import": "./dist/modules/authoring/hooks.mjs",
+      "default": "./dist/modules/authoring/hooks.mjs"
+    },
+    "./tools": {
+      "types": "./dist/modules/authoring/tools.d.mts",
+      "import": "./dist/modules/authoring/tools.mjs",
+      "default": "./dist/modules/authoring/tools.mjs"
+    },
+    "./channels": {
+      "types": "./dist/modules/authoring/channels.d.mts",
+      "import": "./dist/modules/authoring/channels.mjs",
+      "default": "./dist/modules/authoring/channels.mjs"
+    },
+    "./compiler": {
+      "types": "./dist/modules/compiler/index.d.mts",
+      "import": "./dist/modules/compiler/index.mjs",
+      "default": "./dist/modules/compiler/index.mjs"
+    },
+    "./compatibility": {
+      "types": "./dist/modules/compatibility.d.mts",
+      "import": "./dist/modules/compatibility.mjs",
+      "default": "./dist/modules/compatibility.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@finalai/agent-protocol": "0.1.0",
+    "@finalai/agent-provider": "0.1.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "croner": "^10.0.1",
+    "esbuild": "^0.28.2",
+    "json-schema-library": "11.6.5",
+    "re2js": "2.8.6",
+    "yaml": "^2.8.3",
+    "zod": "4.6.5"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/final-company/packages-typescript.git",
+    "directory": "packages/@finalai/agent-definition"
+  }
+}