@noetic-tools/types 0.1.1

package/dist/util/framework-cast.js

@@ -0,0 +1,16 @@
+/**
+ * Explicit cast for framework boundaries where TypeScript's type system
+ * cannot express the relationship between input and output types.
+ *
+ * Used for: pass-through returns (branch null route, loop feedback),
+ * raw LLM text output, type-erased collections, and cross-library bridges.
+ *
+ * This is the single approved location for unsafe type coercion in the codebase.
+ */
+// Declared return type differs from the parameter type intentionally —
+// callers specify T to bridge a framework type gap that TypeScript cannot express.
+// The runtime value is returned unchanged (identity function).
+export function frameworkCast(value) {
+    // @ts-expect-error — intentional unsafe coercion at framework boundary
+    return value;
+}

package/dist/util/message-helpers.d.ts

@@ -0,0 +1,17 @@
+import type { LLMResponse } from '../types/common.js';
+import type { Context } from '../types/context.js';
+import type { InputMessageItem, Item, MessageItem } from '../types/items.js';
+export declare function isAssistantMessage(item: unknown): item is MessageItem;
+export declare function isUserMessage(item: unknown): item is MessageItem;
+export declare function isOutputText(part: {
+    type: string;
+}): part is {
+    type: 'output_text';
+    text: string;
+};
+export declare function createMessage(text: string, role: 'user' | 'developer'): InputMessageItem;
+export declare function extractAssistantText(items: ReadonlyArray<Item>): string;
+/** Naive token estimate: ~4 chars per token */
+export declare function estimateTokens(text: string): number;
+/** Accumulate token usage and cost from an LLM response onto a mutable context. */
+export declare function trackUsage(ctx: Context, response: LLMResponse): void;

package/dist/util/message-helpers.js

@@ -0,0 +1,64 @@
+function canTrackUsage(ctx) {
+    const desc = Object.getOwnPropertyDescriptor(ctx, 'stepCount');
+    return desc !== undefined && desc.writable !== false;
+}
+export function isAssistantMessage(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'message' &&
+        'role' in item &&
+        item.role === 'assistant');
+}
+export function isUserMessage(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'message' &&
+        'role' in item &&
+        item.role === 'user');
+}
+export function isOutputText(part) {
+    return part.type === 'output_text';
+}
+export function createMessage(text, role) {
+    return {
+        id: crypto.randomUUID(),
+        status: 'completed',
+        type: 'message',
+        role,
+        content: [
+            {
+                type: 'input_text',
+                text,
+            },
+        ],
+    };
+}
+export function extractAssistantText(items) {
+    const lastMsg = items.findLast(isAssistantMessage);
+    if (!lastMsg) {
+        return '';
+    }
+    return (lastMsg.content
+        ?.filter(isOutputText)
+        ?.map((c) => c.text)
+        ?.join('') ?? '');
+}
+/** Naive token estimate: ~4 chars per token */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Accumulate token usage and cost from an LLM response onto a mutable context. */
+export function trackUsage(ctx, response) {
+    if (!canTrackUsage(ctx)) {
+        return;
+    }
+    ctx.tokens.input += response.usage.inputTokens;
+    ctx.tokens.output += response.usage.outputTokens;
+    ctx.tokens.total += response.usage.inputTokens + response.usage.outputTokens;
+    ctx.tokens.cached = (ctx.tokens.cached ?? 0) + (response.usage.cachedTokens ?? 0);
+    if (response.cost) {
+        ctx.cost = ctx.cost + response.cost;
+    }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@noetic-tools/types",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mattapperson/noetic.git",
+    "directory": "packages/types"
+  },
+  "homepage": "https://github.com/mattapperson/noetic#readme",
+  "bugs": {
+    "url": "https://github.com/mattapperson/noetic/issues"
+  },
+  "keywords": [
+    "noetic",
+    "agents",
+    "types",
+    "contracts"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/types/memory.d.ts",
+      "default": "./dist/types/memory.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@openrouter/agent": "^0.6.0",
+    "bun-types": "latest"
+  },
+  "peerDependencies": {
+    "@openrouter/agent": "^0.6.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@openrouter/agent": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@openrouter/agent": "^0.6.0",
+    "zod": "^4.0.0"
+  },
+  "scripts": {
+    "build": "bunx tsc -p tsconfig.build.json && bun scripts/add-js-extensions.ts",
+    "verify:esm": "bun scripts/verify-node-esm.ts",
+    "prepublishOnly": "rm -rf dist && bun run build && bun run verify:esm",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov",
+    "test:ci": "bun test --coverage --coverage-reporter=lcov",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "bunx biome check .",
+    "lint:fix": "bunx biome check --fix .",
+    "format": "bunx biome format --write .",
+    "format:check": "bunx biome format ."
+  }
+}