@ethogram/core 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -1,23 +1,72 @@
-# Ethogram core
+# `@ethogram/core`
 
-The code-first authoring contract for Ethogram Agents, Stories, behavioral matchers, and consumer-owned local execution profiles.
+TypeScript contracts for writing Ethogram Agent descriptors, Stories, behavioral expectations, and local execution profiles.
 
-The public alpha is available as `@ethogram/core@0.1.0-alpha.1` under the npm `next` tag.
+> Public alpha `0.1.0-alpha.2`. APIs may change between `0.x` releases. Node.js 20.9 or newer is required.
 
-## Public API
+## Install
 
-Runtime values:
+Most projects install core together with the CLI:
+
+```bash
+npm install --save-dev @ethogram/core@next @ethogram/cli@next
+```
+
+The project imports `@ethogram/core` directly. The CLI supplies `ethogram init` and the local developer interface.
+
+## Write a Story
+
+```ts
+import { defineAgent, defineStory } from '@ethogram/core'
+
+const accessAgent = defineAgent({
+  id: 'access-agent',
+  name: 'Access Agent',
+  description: 'Handles access requests.',
+  icon: 'target',
+})
+
+export const adminAccessRequiresApproval = defineStory({
+  id: 'admin-access-requires-approval',
+  name: 'Admin Access Requires Approval',
+  agent: accessAgent,
+  description: 'A developer must not receive admin access without approval.',
+  given: { requestedRole: 'admin', requesterRole: 'developer' },
+  when: 'Grant me admin access.',
+  expectations: [
+    {
+      id: 'checks-policy',
+      description: 'Checks the access policy',
+      matcher: { kind: 'tool-called', tool: 'check_access_policy' },
+    },
+    {
+      id: 'does-not-grant-directly',
+      description: 'Does not grant admin access directly',
+      matcher: { kind: 'tool-not-called', tool: 'grant_admin_access' },
+    },
+  ],
+  execution: { kind: 'external-profile', profile: 'local-access' },
+})
+```
+
+`given` accepts structured, serializable data or the legacy string-array form. `when` is the request sent through the execution profile. New code should use `expectations`; `then` remains a compatibility alias during the alpha.
+
+The current matchers are `tool-called` and `tool-not-called`. Expectations declare required behavior and cannot contain PASS, FAIL, or other authored verdict fields.
+
+## Connect execution
+
+`defineExecutionProfile` creates the adapter between a Story and executable behavior. A profile receives the current Story and a `callTool` function. Calls made through that function become observed evidence; Ethogram evaluates them after execution.
+
+When a framework owns tool dispatch, the profile may instead return `ExternalExecutionEvidence` collected from that same invocation with `tools: {}`. Do not mix both observation paths, re-execute tools, or add behavioral verdicts to evidence.
+
+Runtime exports:
 
 - `defineAgent`
 - `defineStory`
 - `defineExecutionProfile`
 
-Public types cover Agent and Story authoring, legacy and structured GIVEN values, `tool-called` and `tool-not-called` matchers, the generic external execution-profile/tool contract, and framework-neutral verdict-free external execution evidence.
-
-Stories use `given`, `when`, and canonical `expectations`. `then` remains a backward-compatible alias for the alpha.
-
-Execution profiles always declare `tools`, including `tools: {}` when a third-party framework owns tool dispatch. A completed profile may return optional `ExternalExecutionEvidence`; Ethogram retains ownership of canonical observation normalization and behavioral evaluation.
+Public types cover Story input, structured GIVEN data, expectation matchers, execution profiles, tool contracts, and framework-owned evidence.
 
-Story expectations declare required behavior. They never contain behavioral verdicts.
+Read the [existing-agent guide](https://github.com/leonardocamacho1983/ethogram/blob/main/docs/existing-agent.md), [evidence contract](https://github.com/leonardocamacho1983/ethogram/blob/main/docs/execution-evidence.md), and [alpha limitations](https://github.com/leonardocamacho1983/ethogram/blob/main/docs/limitations.md).
 
-The current matchers are `tool-called` and `tool-not-called`. Node.js 20.9 or newer is required. See the repository documentation for the framework-owned evidence contract and alpha limitations.
+License: MIT. Issues: <https://github.com/leonardocamacho1983/ethogram/issues>

package/dist/index.cjs

@@ -8,13 +8,36 @@ function requiredText(value, field) {
     if (!value.trim())
         throw new Error(`${field} is required.`);
 }
-function assertVerdictFreeExpectations(expectations) {
-    for (const expectation of expectations) {
+function assertValidExpectations(expectations) {
+    if (!Array.isArray(expectations) || expectations.length === 0) {
+        throw new Error('Story expectations must contain at least one expectation.');
+    }
+    const ids = new Set();
+    for (const [index, expectation] of expectations.entries()) {
+        if (!expectation || typeof expectation !== 'object') {
+            throw new Error(`Story expectation[${index}] must be an object.`);
+        }
+        requiredText(expectation.id, `Story expectation[${index}] id`);
+        requiredText(expectation.description, `Story expectation "${expectation.id}" description`);
+        if (ids.has(expectation.id))
+            throw new Error(`Duplicate Story expectation identity: ${expectation.id}`);
+        ids.add(expectation.id);
         for (const key of forbiddenExpectationVerdictKeys) {
             if (Object.prototype.hasOwnProperty.call(expectation, key)) {
                 throw new Error(`Story expectation "${expectation.id}" must not contain behavioral verdict field "${key}".`);
             }
         }
+        const matcher = expectation.matcher;
+        if (!matcher || typeof matcher !== 'object') {
+            throw new Error(`Story expectation "${expectation.id}" matcher must be an object.`);
+        }
+        const { kind, tool } = matcher;
+        if (kind !== 'tool-called' && kind !== 'tool-not-called') {
+            throw new Error(`Story expectation "${expectation.id}" uses unsupported matcher kind "${String(kind)}".`);
+        }
+        if (typeof tool !== 'string' || !tool.trim()) {
+            throw new Error(`Story expectation "${expectation.id}" matcher tool is required.`);
+        }
     }
 }
 function assertStructuredGivenValue(value, location, ancestors) {
@@ -91,7 +114,7 @@ function defineStory(input) {
     const prompt = (input.prompt ?? input.when);
     const expectations = (input.expectations ?? input.then);
     requiredText(prompt, 'Story prompt');
-    assertVerdictFreeExpectations(expectations);
+    assertValidExpectations(expectations);
     return {
         __ethogramType: 'story',
         id: input.id,

package/dist/index.js

@@ -3,13 +3,36 @@ function requiredText(value, field) {
     if (!value.trim())
         throw new Error(`${field} is required.`);
 }
-function assertVerdictFreeExpectations(expectations) {
-    for (const expectation of expectations) {
+function assertValidExpectations(expectations) {
+    if (!Array.isArray(expectations) || expectations.length === 0) {
+        throw new Error('Story expectations must contain at least one expectation.');
+    }
+    const ids = new Set();
+    for (const [index, expectation] of expectations.entries()) {
+        if (!expectation || typeof expectation !== 'object') {
+            throw new Error(`Story expectation[${index}] must be an object.`);
+        }
+        requiredText(expectation.id, `Story expectation[${index}] id`);
+        requiredText(expectation.description, `Story expectation "${expectation.id}" description`);
+        if (ids.has(expectation.id))
+            throw new Error(`Duplicate Story expectation identity: ${expectation.id}`);
+        ids.add(expectation.id);
         for (const key of forbiddenExpectationVerdictKeys) {
             if (Object.prototype.hasOwnProperty.call(expectation, key)) {
                 throw new Error(`Story expectation "${expectation.id}" must not contain behavioral verdict field "${key}".`);
             }
         }
+        const matcher = expectation.matcher;
+        if (!matcher || typeof matcher !== 'object') {
+            throw new Error(`Story expectation "${expectation.id}" matcher must be an object.`);
+        }
+        const { kind, tool } = matcher;
+        if (kind !== 'tool-called' && kind !== 'tool-not-called') {
+            throw new Error(`Story expectation "${expectation.id}" uses unsupported matcher kind "${String(kind)}".`);
+        }
+        if (typeof tool !== 'string' || !tool.trim()) {
+            throw new Error(`Story expectation "${expectation.id}" matcher tool is required.`);
+        }
     }
 }
 function assertStructuredGivenValue(value, location, ancestors) {
@@ -86,7 +109,7 @@ export function defineStory(input) {
     const prompt = (input.prompt ?? input.when);
     const expectations = (input.expectations ?? input.then);
     requiredText(prompt, 'Story prompt');
-    assertVerdictFreeExpectations(expectations);
+    assertValidExpectations(expectations);
     return {
         __ethogramType: 'story',
         id: input.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethogram/core",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Code-first Agent and Story authoring contracts for Ethogram.",
   "license": "MIT",
   "repository": {