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

package/README.md

@@ -1,17 +1,55 @@
-# Ethogram CLI
+# `@ethogram/cli`
 
-Local Ethogram initialization and read-only developer runtime for TypeScript/Node projects.
+The local Ethogram initializer and read-only developer interface for TypeScript and Node.js projects.
 
-The public alpha is available as `@ethogram/cli@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.
+
+## Install
+
+```bash
+npm install --save-dev @ethogram/core@next @ethogram/cli@next
+```
+
+Install core as a direct dependency because generated and hand-written Stories import it. The locally installed CLI is available through `npx ethogram`.
+
+## Try the starter
+
+Run these commands from a project whose `package.json` has a non-empty `name`:
 
 ```bash
 npx ethogram init
-npx ethogram init --existing
 npx ethogram dev
 ```
 
-Use `ethogram init --existing` to create only `ethogram.config.mjs` in a project that already owns an agent implementation. Normal `ethogram init` adds the deterministic Access Request starter. Both modes preserve conflicting user-owned files and abort without partial writes.
+`init` adds a deterministic Access Request example: configuration, an Agent descriptor, a Story, and an execution profile. It checks every target before writing. If it finds conflicting content, it preserves all existing files and writes nothing.
+
+`dev` binds to `127.0.0.1`, opens a read-only browser interface, and uses the current directory as the project root. Select the generated Story and choose **Run Story**. The starter makes no model call and has no external side effects.
+
+## Connect an existing agent
+
+```bash
+npx ethogram init --existing
+```
+
+This mode creates only `ethogram.config.mjs`. Add your own Agent descriptor, Story, and execution profile, then start the interface with `npx ethogram dev`.
+
+## Commands
+
+```text
+ethogram init [--existing]
+ethogram dev [--project <path>] [--port <number>] [--no-open]
+ethogram --help
+ethogram --version
+```
+
+- `--project` loads a project outside the current directory.
+- `--port` changes the default port, `4317`. Port `0` selects an available port.
+- `--no-open` starts the server without opening a browser.
+
+Relevant TypeScript and JavaScript changes reload automatically. A previous result is cleared or marked stale until you run the Story against the new revision. Ethogram does not persist run history.
+
+The package exports `@ethogram/cli/runtime` only for the isolated worker used by `@ethogram/mcp`. It is not a general engine extension API.
 
-`ethogram dev` accepts `--project <path>`, `--port <number>`, and `--no-open`. It serves a localhost-only, code-first UI: project files are the source of truth and the UI does not save edits. Relevant source changes reload automatically, and previous execution evidence is cleared or marked stale until the Story is rerun.
+Read the [starter guide](https://github.com/leonardocamacho1983/ethogram/blob/main/docs/quickstart.md), [existing-agent guide](https://github.com/leonardocamacho1983/ethogram/blob/main/docs/existing-agent.md), and [alpha limitations](https://github.com/leonardocamacho1983/ethogram/blob/main/docs/limitations.md).
 
-Node.js 20.9 or newer is required. Ethogram does not persist run history.
+License: MIT. Issues: <https://github.com/leonardocamacho1983/ethogram/issues>

package/dist/contracts.d.ts

@@ -99,6 +99,14 @@ export type BehavioralVerdict = 'PASS' | 'FAIL';
 export type EvaluationResult = {
     verdict: BehavioralVerdict;
     expectations: Readonly<Record<string, BehavioralVerdict>>;
+    expectationResults: readonly {
+        id: string;
+        description: string;
+        matcher: ExpectationMatcher;
+        verdict: BehavioralVerdict;
+        observedCallCount: number;
+        matchingCallIds: readonly string[];
+    }[];
 };
 export type CompletedExecutionRecord = {
     observedRun: ObservedRun;

package/dist/evaluator.js

@@ -1,15 +1,31 @@
-function evaluateMatcher(matcher, observedRun) {
-    const called = observedRun.toolCalls.some((toolCall) => toolCall.name === matcher.tool);
-    return matcher.kind === 'tool-called' ? called : !called;
+function matchingCalls(matcher, observedRun) {
+    switch (matcher.kind) {
+        case 'tool-called':
+        case 'tool-not-called':
+            return observedRun.toolCalls.filter((toolCall) => toolCall.name === matcher.tool);
+        default: {
+            const unsupported = matcher;
+            throw new Error(`UNSUPPORTED_MATCHER: ${JSON.stringify(unsupported)}`);
+        }
+    }
 }
 export function evaluateStory(story, observedRun) {
-    const expectationEntries = story.expectations.map((expectation) => {
-        const verdict = evaluateMatcher(expectation.matcher, observedRun) ? 'PASS' : 'FAIL';
-        return [expectation.id, verdict];
+    const expectationResults = story.expectations.map((expectation) => {
+        const calls = matchingCalls(expectation.matcher, observedRun);
+        const matched = expectation.matcher.kind === 'tool-called' ? calls.length > 0 : calls.length === 0;
+        const verdict = matched ? 'PASS' : 'FAIL';
+        return Object.freeze({
+            id: expectation.id,
+            description: expectation.description,
+            matcher: expectation.matcher,
+            verdict,
+            observedCallCount: calls.length,
+            matchingCallIds: Object.freeze(calls.map(({ callId }) => callId)),
+        });
     });
-    const expectations = Object.freeze(Object.fromEntries(expectationEntries));
-    const verdict = Object.values(expectations).every((value) => value === 'PASS')
+    const expectations = Object.freeze(Object.fromEntries(expectationResults.map(({ id, verdict }) => [id, verdict])));
+    const verdict = expectationResults.every(({ verdict: value }) => value === 'PASS')
         ? 'PASS'
         : 'FAIL';
-    return Object.freeze({ verdict, expectations });
+    return Object.freeze({ verdict, expectations, expectationResults: Object.freeze(expectationResults) });
 }

package/dist/generic-engine.d.ts

@@ -8,7 +8,7 @@ export type EngineRunResult = {
         runner: 'LanguageAdapterRunner';
         evaluator: 'deterministic';
         storyUnchanged: boolean;
-        mockDataUsed: false;
+        mockDataUsed: 'unknown';
     };
 };
 export declare class EthogramEngine {
@@ -17,5 +17,5 @@ export declare class EthogramEngine {
     constructor(runner: LanguageAdapter);
     loadProject(projectRoot: string): Promise<ProjectDescriptor>;
     getProject(): ProjectDescriptor;
-    runStory(storyId: string): Promise<EngineRunResult>;
+    runStory(storyId: string, executionId?: string): Promise<EngineRunResult>;
 }

package/dist/generic-engine.js

@@ -26,7 +26,7 @@ export class EthogramEngine {
             throw new Error('PROJECT_NOT_LOADED');
         return this.project;
     }
-    async runStory(storyId) {
+    async runStory(storyId, executionId = randomUUID()) {
         const project = this.getProject();
         const story = project.stories.find((candidate) => candidate.id === storyId);
         if (!story)
@@ -41,13 +41,13 @@ export class EthogramEngine {
         return {
             execution: { observedRun, evaluationResult },
             boundaryEvidence: {
-                executionId: randomUUID(),
+                executionId,
                 completedBehavioralRuns: 1,
                 adapter: this.runner.id,
                 runner: 'LanguageAdapterRunner',
                 evaluator: 'deterministic',
                 storyUnchanged: canonical(story) === storySnapshot,
-                mockDataUsed: false,
+                mockDataUsed: 'unknown',
             },
         };
     }

package/dist/project-runtime.d.ts

@@ -0,0 +1,34 @@
+import { type EngineRunResult } from './generic-engine.js';
+import type { ProjectDescriptor } from './contracts.js';
+export type ProjectSnapshot = {
+    revision: string;
+    project: ProjectDescriptor;
+    storyDigests: Readonly<Record<string, string>>;
+};
+export type ProjectOperationRequest = {
+    kind: 'inspect';
+} | {
+    kind: 'run';
+    storyId: string;
+    expectedRevision: string;
+    expectedStoryDigest: string;
+    executionId?: string;
+};
+export type ProjectOperationResult = {
+    kind: 'inspect';
+    snapshot: ProjectSnapshot;
+} | {
+    kind: 'run';
+    snapshot: ProjectSnapshot;
+    run: EngineRunResult;
+};
+export type ProjectOperationOptions = {
+    beforeRun?: (snapshot: ProjectSnapshot) => void | Promise<void>;
+};
+export declare class ProjectRuntimeError extends Error {
+    readonly code: string;
+    readonly effectsMayHaveOccurred: boolean;
+    readonly retrySafe: boolean;
+    constructor(code: string, message: string, effectsMayHaveOccurred?: boolean, retrySafe?: boolean);
+}
+export declare function executeProjectOperation(projectRoot: string, request: ProjectOperationRequest, options?: ProjectOperationOptions): Promise<ProjectOperationResult>;

package/dist/project-runtime.js

@@ -0,0 +1,144 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { EthogramEngine } from './generic-engine.js';
+import { TypeScriptAdapter, TypeScriptAdapterError } from './typescript-adapter.js';
+const ignoredDirectories = new Set([
+    '.git', '.next', '.turbo', '.vercel', 'build', 'coverage', 'dist', 'node_modules',
+]);
+const sourceExtensions = new Set(['.cjs', '.cts', '.js', '.json', '.mjs', '.mts', '.ts']);
+export class ProjectRuntimeError extends Error {
+    code;
+    effectsMayHaveOccurred;
+    retrySafe;
+    constructor(code, message, effectsMayHaveOccurred = false, retrySafe = !effectsMayHaveOccurred) {
+        super(message);
+        this.code = code;
+        this.effectsMayHaveOccurred = effectsMayHaveOccurred;
+        this.retrySafe = retrySafe;
+        this.name = 'ProjectRuntimeError';
+    }
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, nested]) => `${JSON.stringify(key)}:${stableJson(nested)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function digest(value) {
+    return createHash('sha256').update(stableJson(value)).digest('hex');
+}
+async function projectSourceDigest(projectRoot) {
+    const files = [];
+    async function visit(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            if (ignoredDirectories.has(entry.name))
+                continue;
+            const absolute = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await visit(absolute);
+            }
+            else if (entry.isFile() && sourceExtensions.has(path.extname(entry.name))) {
+                files.push(absolute);
+            }
+        }
+    }
+    await visit(projectRoot);
+    files.sort();
+    const hash = createHash('sha256');
+    for (const file of files) {
+        hash.update(path.relative(projectRoot, file).split(path.sep).join('/'));
+        hash.update('\0');
+        hash.update(await readFile(file));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+function runtimeError(error, effectsMayHaveOccurred = false) {
+    if (error instanceof ProjectRuntimeError)
+        return error;
+    if (error instanceof TypeScriptAdapterError) {
+        return new ProjectRuntimeError(error.code, error.message, effectsMayHaveOccurred, !effectsMayHaveOccurred);
+    }
+    if (error instanceof Error) {
+        const [candidate] = error.message.slice(0, 128).split(':', 1);
+        const code = /^[A-Z][A-Z_]+$/.test(candidate) ? candidate : 'ETHOGRAM_RUNTIME_ERROR';
+        return new ProjectRuntimeError(code, error.message, effectsMayHaveOccurred, !effectsMayHaveOccurred);
+    }
+    return new ProjectRuntimeError('ETHOGRAM_RUNTIME_ERROR', 'The Ethogram runtime operation failed.', effectsMayHaveOccurred, !effectsMayHaveOccurred);
+}
+async function stableSnapshot(projectRoot, expectedRevision) {
+    let root;
+    try {
+        root = await realpath(projectRoot);
+        if (!(await stat(root)).isDirectory())
+            throw new Error('not-directory');
+    }
+    catch {
+        throw new ProjectRuntimeError('INVALID_PROJECT_ROOT', 'The configured project root is not a readable directory.');
+    }
+    const before = await projectSourceDigest(root);
+    if (expectedRevision !== undefined && before !== expectedRevision) {
+        throw new ProjectRuntimeError('STALE_PROJECT', 'The project revision no longer matches the inspected revision.');
+    }
+    const engine = new EthogramEngine(new TypeScriptAdapter());
+    let project;
+    try {
+        project = await engine.loadProject(root);
+    }
+    catch (error) {
+        throw runtimeError(error, true);
+    }
+    const after = await projectSourceDigest(root);
+    if (before !== after) {
+        throw new ProjectRuntimeError('STALE_PROJECT', 'Project sources changed while Ethogram was loading them.', true, false);
+    }
+    const storyDigests = Object.freeze(Object.fromEntries(project.stories.map((story) => [story.id, digest(story)])));
+    return { snapshot: Object.freeze({ revision: after, project, storyDigests }), engine };
+}
+export async function executeProjectOperation(projectRoot, request, options = {}) {
+    const { snapshot, engine } = await stableSnapshot(projectRoot, request.kind === 'run' ? request.expectedRevision : undefined);
+    if (request.kind === 'inspect')
+        return { kind: 'inspect', snapshot };
+    if (request.expectedRevision !== snapshot.revision) {
+        throw new ProjectRuntimeError('STALE_PROJECT', 'The project revision no longer matches the inspected revision.');
+    }
+    const storyDigest = snapshot.storyDigests[request.storyId];
+    if (!storyDigest) {
+        throw new ProjectRuntimeError('STORY_NOT_FOUND', 'The requested Story does not exist in the current project.', true, false);
+    }
+    if (storyDigest !== request.expectedStoryDigest) {
+        throw new ProjectRuntimeError('STALE_PROJECT', 'The Story contract no longer matches the inspected Story digest.', true, false);
+    }
+    try {
+        await options.beforeRun?.(snapshot);
+    }
+    catch (error) {
+        throw runtimeError(error, true);
+    }
+    const executionId = request.executionId ?? randomUUID();
+    let run;
+    try {
+        run = await engine.runStory(request.storyId, executionId);
+    }
+    catch (error) {
+        throw runtimeError(error, true);
+    }
+    let afterRun;
+    try {
+        afterRun = await projectSourceDigest(snapshot.project.projectRoot);
+    }
+    catch (error) {
+        throw runtimeError(error, true);
+    }
+    if (afterRun !== snapshot.revision) {
+        throw new ProjectRuntimeError('STALE_EXECUTION', 'Project sources changed after execution started.', true, false);
+    }
+    return { kind: 'run', snapshot, run };
+}

package/dist/templates.js

@@ -36,11 +36,10 @@ export const adminAccessRequiresApproval = defineStory({
   name: 'Admin Access Requires Approval',
   agent: accessRequestAgent,
   description: 'Administrative access requested by a developer requires approval.',
-  given: [
-    'requestedRole: admin',
-    'requesterRole: developer',
-    'approvalRequired: true',
-  ],
+  given: {
+    requestedRole: 'admin',
+    requesterRole: 'developer',
+  },
   when: 'Grant me admin access.',
   expectations: [
     {
@@ -64,7 +63,24 @@ export const adminAccessRequiresApproval = defineStory({
         },
         {
             relativePath: 'execution/access-request.profile.ts',
-            content: `import { defineExecutionProfile } from '@ethogram/core'
+            content: `import { defineExecutionProfile, type Story } from '@ethogram/core'
+
+type AccessRequestInput = {
+  requestedRole: string
+  requesterRole: string
+  instruction: string
+}
+
+function storyInput(story: Story): AccessRequestInput {
+  if (Array.isArray(story.given)) {
+    throw new Error('The Access Request Story requires structured GIVEN data.')
+  }
+  const { requestedRole, requesterRole } = story.given
+  if (typeof requestedRole !== 'string' || typeof requesterRole !== 'string') {
+    throw new Error('requestedRole and requesterRole must be strings.')
+  }
+  return { requestedRole, requesterRole, instruction: story.prompt }
+}
 
 export const accessRequestProfile = defineExecutionProfile({
   id: 'local-access-request',
@@ -90,8 +106,8 @@ export const accessRequestProfile = defineExecutionProfile({
       }),
     },
   },
-  async execute({ callTool }) {
-    const input = { requestedRole: 'admin', requesterRole: 'developer' }
+  async execute({ story, callTool }) {
+    const input = storyInput(story)
     const policy = await callTool('check_access_policy', input)
     if (policy.approvalRequired === true) {
       await callTool('request_access_approval', input)

package/dist/typescript-adapter.d.ts

@@ -1,5 +1,5 @@
 import type { ExecutionRequest, LanguageAdapter, ObservedRun, ProjectDescriptor } from './contracts.js';
-export type TypeScriptAdapterErrorCode = 'INVALID_PROJECT_ROOT' | 'MISSING_PROJECT_PACKAGE' | 'MISSING_ETHOGRAM_CONFIG' | 'INVALID_ETHOGRAM_CONFIG' | 'NO_STORIES' | 'INVALID_AGENT_EXPORT' | 'INVALID_STORY_EXPORT' | 'INVALID_EXECUTION_PROFILE_EXPORT' | 'DUPLICATE_AGENT_ID' | 'DUPLICATE_STORY_ID' | 'DUPLICATE_EXECUTION_PROFILE_ID' | 'UNKNOWN_STORY_AGENT' | 'UNKNOWN_EXECUTION_PROFILE' | 'INVALID_EXTERNAL_EXECUTION_EVIDENCE' | 'CONFLICTING_OBSERVATION_SOURCES' | 'PROFILE_EXECUTION_FAILED';
+export type TypeScriptAdapterErrorCode = 'INVALID_PROJECT_ROOT' | 'MISSING_PROJECT_PACKAGE' | 'MISSING_ETHOGRAM_CONFIG' | 'INVALID_ETHOGRAM_CONFIG' | 'PROJECT_PATH_ESCAPE' | 'NO_STORIES' | 'INVALID_AGENT_EXPORT' | 'INVALID_STORY_EXPORT' | 'INVALID_EXECUTION_PROFILE_EXPORT' | 'DUPLICATE_AGENT_ID' | 'DUPLICATE_STORY_ID' | 'DUPLICATE_EXECUTION_PROFILE_ID' | 'UNKNOWN_STORY_AGENT' | 'UNKNOWN_EXECUTION_PROFILE' | 'INVALID_EXTERNAL_EXECUTION_EVIDENCE' | 'CONFLICTING_OBSERVATION_SOURCES' | 'PROFILE_EXECUTION_FAILED';
 export declare class TypeScriptAdapterError extends Error {
     readonly code: TypeScriptAdapterErrorCode;
     constructor(code: TypeScriptAdapterErrorCode, message: string);

package/dist/typescript-adapter.js

@@ -1,4 +1,4 @@
-import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { lstat, readdir, readFile, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { build } from 'esbuild';
 import { ExternalEvidenceValidationError, normalizeExternalExecutionEvidence, } from './external-evidence.js';
@@ -16,9 +16,14 @@ function isRecord(value) {
 function isAgent(value) {
     return isRecord(value)
         && typeof value.id === 'string'
+        && value.id.length > 0
+        && value.id.length <= 200
         && typeof value.name === 'string'
+        && value.name.length <= 1_000
         && typeof value.description === 'string'
-        && typeof value.icon === 'string';
+        && value.description.length <= 4_000
+        && typeof value.icon === 'string'
+        && value.icon.length <= 200;
 }
 function isGivenValue(value, ancestors) {
     if (value === null || typeof value === 'string' || typeof value === 'boolean')
@@ -51,21 +56,60 @@ function isGiven(value) {
         ? value.every((entry) => typeof entry === 'string')
         : isGivenValue(value, new Set()) && Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
+function isJsonRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value))
+        && isGivenValue(value, new Set());
+}
 function isStory(value) {
     return isRecord(value)
         && value.__ethogramType === 'story'
         && typeof value.id === 'string'
+        && value.id.length > 0
+        && value.id.length <= 200
         && typeof value.name === 'string'
+        && value.name.length <= 1_000
         && isAgent(value.agent)
         && typeof value.description === 'string'
+        && value.description.length <= 4_000
         && isGiven(value.given)
         && typeof value.prompt === 'string'
-        && Array.isArray(value.expectations);
+        && value.prompt.length <= 128_000
+        && Array.isArray(value.expectations)
+        && value.expectations.length > 0
+        && (() => {
+            const ids = new Set();
+            return value.expectations.every((candidate) => {
+                if (!isRecord(candidate)
+                    || typeof candidate.id !== 'string'
+                    || !candidate.id.trim()
+                    || candidate.id.length > 200
+                    || ids.has(candidate.id)
+                    || typeof candidate.description !== 'string'
+                    || !candidate.description.trim()
+                    || candidate.description.length > 4_000
+                    || (candidate.failureDescription !== undefined
+                        && (typeof candidate.failureDescription !== 'string'
+                            || !candidate.failureDescription.trim()
+                            || candidate.failureDescription.length > 4_000))
+                    || !isRecord(candidate.matcher)
+                    || (candidate.matcher.kind !== 'tool-called' && candidate.matcher.kind !== 'tool-not-called')
+                    || typeof candidate.matcher.tool !== 'string'
+                    || !candidate.matcher.tool.trim()
+                    || candidate.matcher.tool.length > 200
+                    || ['passed', 'failed', 'status', 'verdict'].some((key) => Object.prototype.hasOwnProperty.call(candidate, key))) {
+                    return false;
+                }
+                ids.add(candidate.id);
+                return true;
+            });
+        })();
 }
 function isProfile(value) {
     return isRecord(value)
         && value.__ethogramType === 'execution-profile'
         && typeof value.id === 'string'
+        && value.id.length > 0
+        && value.id.length <= 200
         && isRecord(value.tools)
         && typeof value.execute === 'function';
 }
@@ -80,7 +124,7 @@ function deepFreeze(value) {
     }
     return value;
 }
-async function allFiles(root, directories) {
+async function allFiles(directories) {
     const files = [];
     async function visit(directory) {
         let entries;
@@ -96,29 +140,81 @@ async function allFiles(root, directories) {
             const absolute = path.join(directory, entry.name);
             if (entry.isDirectory())
                 await visit(absolute);
-            else
+            else if (entry.isFile() || entry.isSymbolicLink())
                 files.push(absolute);
         }
     }
     for (const directory of directories)
-        await visit(path.resolve(root, directory));
+        await visit(directory);
     return [...new Set(files)].sort();
 }
+function isInside(root, candidate) {
+    const relativePath = path.relative(root, candidate);
+    return relativePath === '' || (!relativePath.startsWith(`..${path.sep}`) && relativePath !== '..' && !path.isAbsolute(relativePath));
+}
+async function confinedDirectories(root, entries, field) {
+    const directories = [];
+    for (const entry of entries) {
+        if (path.isAbsolute(entry)) {
+            throw new TypeScriptAdapterError('PROJECT_PATH_ESCAPE', `${field} must contain project-relative paths: ${entry}`);
+        }
+        const resolved = path.resolve(root, entry);
+        if (!isInside(root, resolved)) {
+            throw new TypeScriptAdapterError('PROJECT_PATH_ESCAPE', `${field} path escapes the project root: ${entry}`);
+        }
+        let canonical = resolved;
+        try {
+            canonical = await realpath(resolved);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (!isInside(root, canonical)) {
+            throw new TypeScriptAdapterError('PROJECT_PATH_ESCAPE', `${field} path resolves outside the project root: ${entry}`);
+        }
+        directories.push(canonical);
+    }
+    return directories;
+}
 function matches(filePath, stem) {
     return ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'].some((extension) => filePath.endsWith(`${stem}${extension}`));
 }
-async function importNativeModule(filePath) {
+async function importNativeModule(filePath, projectRoot) {
     try {
         const result = await build({
             entryPoints: [filePath],
+            absWorkingDir: projectRoot,
             bundle: true,
             platform: 'node',
             format: 'esm',
             target: 'node20',
             write: false,
             sourcemap: false,
+            metafile: true,
             logLevel: 'silent',
         });
+        for (const [importer, metadata] of Object.entries(result.metafile.inputs)) {
+            const importerPath = path.isAbsolute(importer) ? importer : path.resolve(projectRoot, importer);
+            if (!isInside(projectRoot, importerPath))
+                continue;
+            for (const imported of metadata.imports) {
+                const original = imported.original ?? imported.path;
+                if (!original.startsWith('.') && !path.isAbsolute(original))
+                    continue;
+                const resolved = path.isAbsolute(imported.path) ? imported.path : path.resolve(projectRoot, imported.path);
+                let canonical = resolved;
+                try {
+                    canonical = await realpath(resolved);
+                }
+                catch {
+                    // esbuild owns missing-import diagnostics; this check only narrows resolved inputs.
+                }
+                if (!isInside(projectRoot, canonical)) {
+                    throw new TypeScriptAdapterError('PROJECT_PATH_ESCAPE', `A project-relative import resolves outside the project root: ${original}`);
+                }
+            }
+        }
         const source = result.outputFiles[0]?.contents;
         if (!source)
             throw new Error('The TypeScript adapter produced no executable module.');
@@ -126,6 +222,8 @@ async function importNativeModule(filePath) {
         return await import(moduleUrl);
     }
     catch (error) {
+        if (error instanceof TypeScriptAdapterError)
+            throw error;
         const detail = error instanceof Error ? error.message.split('\n')[0] : 'Unknown module-loading error.';
         throw new TypeScriptAdapterError(filePath.includes('.stories.') ? 'INVALID_STORY_EXPORT' : 'INVALID_EXECUTION_PROFILE_EXPORT', `Could not load ${filePath}: ${detail}`);
     }
@@ -170,25 +268,38 @@ export class TypeScriptAdapter {
         }
         let packageName;
         try {
-            const packageJson = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+            const packagePath = path.join(root, 'package.json');
+            const packageMetadata = await lstat(packagePath);
+            if (packageMetadata.isSymbolicLink() || !packageMetadata.isFile()) {
+                throw new TypeScriptAdapterError('PROJECT_PATH_ESCAPE', 'package.json must be a regular file inside the project root.');
+            }
+            const packageJson = JSON.parse(await readFile(packagePath, 'utf8'));
             if (typeof packageJson.name !== 'string' || !packageJson.name.trim())
                 throw new Error('missing-name');
             packageName = packageJson.name;
         }
-        catch {
+        catch (error) {
+            if (error instanceof TypeScriptAdapterError)
+                throw error;
             throw new TypeScriptAdapterError('MISSING_PROJECT_PACKAGE', `Project ${root} must contain a package.json with a name.`);
         }
         const configPath = path.join(root, 'ethogram.config.mjs');
         try {
-            if (!(await stat(configPath)).isFile())
+            const configMetadata = await lstat(configPath);
+            if (configMetadata.isSymbolicLink()) {
+                throw new TypeScriptAdapterError('PROJECT_PATH_ESCAPE', 'ethogram.config.mjs must not be a symbolic link.');
+            }
+            if (!configMetadata.isFile())
                 throw new Error('not-file');
         }
-        catch {
+        catch (error) {
+            if (error instanceof TypeScriptAdapterError)
+                throw error;
             throw new TypeScriptAdapterError('MISSING_ETHOGRAM_CONFIG', `Project ${root} is not initialized. Run "ethogram init" first.`);
         }
         let config;
         try {
-            const module = await importNativeModule(configPath);
+            const module = await importNativeModule(configPath, root);
             if (!isRecord(module.default))
                 throw new Error('missing-default');
             config = module.default;
@@ -199,22 +310,32 @@ export class TypeScriptAdapter {
             }
             throw new TypeScriptAdapterError('INVALID_ETHOGRAM_CONFIG', `Invalid ethogram.config.mjs in ${root}.`);
         }
-        const agentDirectories = config.agentDirectories ?? ['agents'];
-        const storyDirectories = config.storyDirectories ?? ['stories'];
-        const executionDirectories = config.executionDirectories ?? ['execution'];
-        if (![agentDirectories, storyDirectories, executionDirectories].every((entries) => Array.isArray(entries) && entries.every((entry) => typeof entry === 'string' && entry.length > 0))) {
+        const configuredAgentDirectories = config.agentDirectories ?? ['agents'];
+        const configuredStoryDirectories = config.storyDirectories ?? ['stories'];
+        const configuredExecutionDirectories = config.executionDirectories ?? ['execution'];
+        if (![configuredAgentDirectories, configuredStoryDirectories, configuredExecutionDirectories].every((entries) => Array.isArray(entries) && entries.every((entry) => typeof entry === 'string' && entry.length > 0))) {
             throw new TypeScriptAdapterError('INVALID_ETHOGRAM_CONFIG', 'Ethogram directory configuration must contain string arrays.');
         }
+        const [agentDirectories, storyDirectories, executionDirectories] = await Promise.all([
+            confinedDirectories(root, configuredAgentDirectories, 'agentDirectories'),
+            confinedDirectories(root, configuredStoryDirectories, 'storyDirectories'),
+            confinedDirectories(root, configuredExecutionDirectories, 'executionDirectories'),
+        ]);
         const [agentFiles, storyFiles, profileFiles] = await Promise.all([
-            allFiles(root, agentDirectories),
-            allFiles(root, storyDirectories),
-            allFiles(root, executionDirectories),
+            allFiles(agentDirectories),
+            allFiles(storyDirectories),
+            allFiles(executionDirectories),
         ]);
         const selectedAgentFiles = agentFiles.filter((file) => matches(file, '.agent'));
         const selectedStoryFiles = storyFiles.filter((file) => matches(file, '.agent.stories'));
         const selectedProfileFiles = profileFiles.filter((file) => matches(file, '.profile') || matches(file, '-profile'));
+        await Promise.all([...selectedAgentFiles, ...selectedStoryFiles, ...selectedProfileFiles].map(async (file) => {
+            if ((await lstat(file)).isSymbolicLink()) {
+                throw new TypeScriptAdapterError('PROJECT_PATH_ESCAPE', `Ethogram source entrypoints must not be symbolic links: ${relative(root, file)}`);
+            }
+        }));
         const agentEntries = (await Promise.all(selectedAgentFiles.map(async (file) => {
-            const module = await importNativeModule(file);
+            const module = await importNativeModule(file, root);
             const values = Object.values(module).filter(isAgent);
             if (values.length === 0) {
                 throw new TypeScriptAdapterError('INVALID_AGENT_EXPORT', `No valid Agent export found in ${relative(root, file)}.`);
@@ -222,7 +343,7 @@ export class TypeScriptAdapter {
             return values.map((value) => ({ value, source: relative(root, file) }));
         }))).flat();
         const storyEntries = (await Promise.all(selectedStoryFiles.map(async (file) => {
-            const module = await importNativeModule(file);
+            const module = await importNativeModule(file, root);
             const values = Object.values(module).filter(isStory);
             if (values.length === 0) {
                 throw new TypeScriptAdapterError('INVALID_STORY_EXPORT', `No valid Story export found in ${relative(root, file)}.`);
@@ -230,7 +351,7 @@ export class TypeScriptAdapter {
             return values.map((value) => ({ value, source: relative(root, file) }));
         }))).flat();
         const profileEntries = (await Promise.all(selectedProfileFiles.map(async (file) => {
-            const module = await importNativeModule(file);
+            const module = await importNativeModule(file, root);
             const values = Object.values(module).filter(isProfile);
             if (values.length === 0) {
                 throw new TypeScriptAdapterError('INVALID_EXECUTION_PROFILE_EXPORT', `No valid execution profile export found in ${relative(root, file)}.`);
@@ -286,6 +407,9 @@ export class TypeScriptAdapter {
             const outcome = await binding.profile.execute({
                 story: binding.story,
                 callTool: async (name, input) => {
+                    if (typeof name !== 'string' || !name.trim() || name.length > 200 || !isJsonRecord(input)) {
+                        throw new TypeScriptAdapterError('PROFILE_EXECUTION_FAILED', 'PROFILE_EXECUTION_FAILED: callTool requires a bounded tool name and a finite JSON object input.');
+                    }
                     const tool = binding.profile.tools[name];
                     if (!tool)
                         throw new Error(`Execution profile requested unavailable tool: ${name}`);
@@ -302,6 +426,9 @@ export class TypeScriptAdapter {
                     trace.push(invocation);
                     try {
                         const output = await tool.execute(cloneRecord(input));
+                        if (!isJsonRecord(output)) {
+                            throw new TypeScriptAdapterError('PROFILE_EXECUTION_FAILED', 'PROFILE_EXECUTION_FAILED: an intercepted tool must return a finite JSON object output.');
+                        }
                         invocation.output = cloneRecord(output);
                         return cloneRecord(output);
                     }
@@ -320,6 +447,11 @@ export class TypeScriptAdapter {
                     }
                 },
             });
+            if (!outcome || typeof outcome !== 'object'
+                || typeof outcome.decision !== 'string'
+                || typeof outcome.finalResponse !== 'string') {
+                throw new TypeScriptAdapterError('PROFILE_EXECUTION_FAILED', 'PROFILE_EXECUTION_FAILED: The execution profile must return string decision and finalResponse fields.');
+            }
             if (outcome.evidence !== undefined && trace.length > 0) {
                 throw new TypeScriptAdapterError('CONFLICTING_OBSERVATION_SOURCES', 'CONFLICTING_OBSERVATION_SOURCES: A Run cannot use both Ethogram callTool evidence and external execution evidence.');
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethogram/cli",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Local Ethogram initialization and read-only developer runtime.",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,12 @@
   },
   "keywords": ["ai-agents", "behavioral-testing", "typescript", "cli"],
   "type": "module",
+  "exports": {
+    "./runtime": {
+      "types": "./dist/project-runtime.d.ts",
+      "import": "./dist/project-runtime.js"
+    }
+  },
   "bin": {
     "ethogram": "dist/cli.js"
   },
@@ -28,7 +34,7 @@
     "node": ">=20.9"
   },
   "dependencies": {
-    "@ethogram/core": "0.1.0-alpha.1",
+    "@ethogram/core": "0.1.0-alpha.2",
     "esbuild": "^0.28.2"
   },
   "scripts": {