@agentick/core 0.0.1

package/dist/tentickle-instance.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Tentickle Configuration Instance
+ *
+ * `Tentickle` is the default global instance. Users interact with instances, never the class directly.
+ *
+ * ```typescript
+ * import { Tentickle, createApp } from 'tentickle';
+ *
+ * // Configure global instance
+ * Tentickle.use('*', loggingMiddleware);
+ * Tentickle.use('tool:*', authMiddleware);
+ *
+ * // createApp uses Tentickle by default
+ * const app = createApp(MyAgent, { model });
+ *
+ * // Create a scoped instance (inherits from Tentickle)
+ * const scoped = Tentickle.create();
+ * scoped.use('model:generate', rateLimitMiddleware);
+ * const scopedApp = scoped.createApp(MyAgent, { model });
+ *
+ * // Create isolated instance (no inheritance)
+ * const isolated = Tentickle.create({ inheritDefaults: false });
+ * ```
+ *
+ * @module tentickle/@tentickle/instance
+ */
+import { type Middleware, type TelemetryProvider, type Procedure } from "@tentickle/kernel";
+import type { App, RunInput, AppOptions, SessionExecutionHandle, ComponentFunction } from "./app/types";
+/**
+ * Key for middleware registration.
+ * - `'*'` - matches all procedures
+ * - `'tool:*'` - matches all tool procedures
+ * - `'tool:run'` - matches specific procedure
+ * - `'model:generate'` - matches specific procedure
+ */
+export type MiddlewareKey = string;
+/**
+ * Options for creating an TentickleInstance.
+ */
+export interface TentickleInstanceCreateOptions {
+    /** Telemetry provider for tracing and metrics */
+    telemetryProvider?: TelemetryProvider;
+    /**
+     * Whether to inherit middleware from the parent instance.
+     * @default true
+     */
+    inheritDefaults?: boolean;
+}
+/**
+ * Interface for middleware resolution.
+ * This is what gets passed to context for procedures to read at execution time.
+ */
+export interface MiddlewareRegistry {
+    /**
+     * Get middleware matching a procedure name.
+     * Matches in order: '*', category wildcard ('tool:*'), exact name
+     */
+    getMiddlewareFor(procedureName: string): Middleware[];
+}
+/**
+ * Handler type for the run procedure.
+ * Generic P is the props type for the component.
+ */
+type RunHandler = <P extends Record<string, unknown>>(element: {
+    type: ComponentFunction<P>;
+    props: P;
+    key: string | number | null;
+}, input?: RunInput<P>) => SessionExecutionHandle;
+/**
+ * Tentickle configuration instance.
+ *
+ * Users interact with instances, never the class directly.
+ * `Tentickle` is the default global instance.
+ */
+export declare class TentickleInstance implements MiddlewareRegistry {
+    private middlewareRegistry;
+    private _telemetryProvider?;
+    /**
+     * One-shot execution of a JSX component.
+     *
+     * Accepts a JSX element and optional RunInput. Creates a temporary app and session,
+     * runs to completion, then cleans up.
+     *
+     * **Prop merging:** Element props are defaults, `input.props` override them.
+     * `{ ...element.props, ...input.props }` — so `<Agent query="default" />` with
+     * `{ props: { query: "override" } }` uses `"override"`.
+     *
+     * Returns SessionExecutionHandle (AsyncIterable, not PromiseLike):
+     * - `await run(...).result` → SendResult
+     * - `for await (const event of await run(...))` → StreamEvent
+     *
+     * @example Get result
+     * ```typescript
+     * const result = await Tentickle.run(
+     *   <MyAgent />,
+     *   { messages: [{ role: "user", content: [...] }], model }
+     * ).result;
+     * ```
+     *
+     * @example Stream events
+     * ```typescript
+     * const handle = await Tentickle.run(<MyAgent />, { messages, model });
+     * for await (const event of handle) {
+     *   if (event.type === 'content_delta') {
+     *     process.stdout.write(event.delta);
+     *   }
+     * }
+     * ```
+     *
+     * @example Add middleware to run
+     * ```typescript
+     * const loggedRun = Tentickle.run.use(loggingMiddleware);
+     * const result = await loggedRun(<MyAgent />, { messages, model }).result;
+     * ```
+     */
+    readonly run: Procedure<RunHandler, true>;
+    /**
+     * @internal
+     */
+    constructor(options?: {
+        telemetryProvider?: TelemetryProvider;
+    });
+    /**
+     * Register middleware for a procedure pattern.
+     *
+     * Keys can be:
+     * - `'*'` - all procedures
+     * - `'tool:*'` - all tool procedures (tool:run, etc.)
+     * - `'model:*'` - all model procedures (model:generate, model:stream)
+     * - `'tool:run'` - specific procedure name
+     * - `'model:generate'` - specific procedure name
+     *
+     * Middleware is executed in order: global → category → specific
+     *
+     * @param key - Procedure pattern to match
+     * @param middleware - Middleware functions to register
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * Tentickle
+     *   .use('*', loggingMiddleware)
+     *   .use('tool:*', authMiddleware)
+     *   .use('model:generate', rateLimitMiddleware);
+     * ```
+     */
+    use(key: MiddlewareKey, ...middleware: Middleware[]): this;
+    /**
+     * Get middleware matching a procedure name.
+     *
+     * Resolution order:
+     * 1. Global ('*')
+     * 2. Category wildcard (e.g., 'tool:*' matches 'tool:run')
+     * 3. Exact match (e.g., 'tool:run')
+     *
+     * @param procedureName - The procedure name to match (e.g., 'tool:run', 'model:generate')
+     * @returns Array of middleware functions in execution order
+     */
+    getMiddlewareFor(procedureName: string): Middleware[];
+    /**
+     * Clear all registered middleware.
+     * Useful for testing or resetting state.
+     */
+    clear(): this;
+    /**
+     * Get the telemetry provider.
+     */
+    get telemetryProvider(): TelemetryProvider | undefined;
+    /**
+     * Set the telemetry provider.
+     */
+    set telemetryProvider(provider: TelemetryProvider | undefined);
+    /**
+     * Create a child instance.
+     *
+     * By default, the child inherits all middleware from this instance.
+     * Use `inheritDefaults: false` for a completely isolated instance.
+     *
+     * @param options - Instance options
+     * @returns A new TentickleInstance
+     *
+     * @example
+     * ```typescript
+     * // Create scoped instance that inherits global middleware
+     * const scoped = Tentickle.create();
+     * scoped.use('model:generate', rateLimitMiddleware);
+     * const app = scoped.createApp(MyAgent);
+     *
+     * // Create isolated instance (no inheritance)
+     * const isolated = Tentickle.create({ inheritDefaults: false });
+     * ```
+     */
+    create(options?: TentickleInstanceCreateOptions): TentickleInstance;
+    /**
+     * Create an app from a component function.
+     *
+     * The app inherits middleware from this Tentickle instance.
+     *
+     * @param Component - The component function that defines the Model Interface
+     * @param options - App configuration options
+     * @returns An App instance with run, send, and session methods
+     *
+     * @example
+     * ```typescript
+     * const MyAgent = ({ query }) => (
+     *   <>
+     *     <System>You are helpful.</System>
+     *     <Timeline />
+     *     <User>{query}</User>
+     *   </>
+     * );
+     *
+     * // Use global Tentickle
+     * const app = createApp(MyAgent, { model });
+     *
+     * // Use scoped instance
+     * const scoped = Tentickle.create();
+     * scoped.use('tool:*', authMiddleware);
+     * const scopedApp = scoped.createApp(MyAgent, { model });
+     * ```
+     */
+    createApp<P extends Record<string, unknown>>(Component: ComponentFunction<P>, options?: AppOptions): App<P>;
+}
+/**
+ * The default global Tentickle instance.
+ *
+ * All configuration and middleware registration starts here.
+ * The exported `createApp` and `run` are bound to this instance.
+ *
+ * @example
+ * ```typescript
+ * import { Tentickle, createApp, run } from 'tentickle';
+ *
+ * // Configure global middleware
+ * Tentickle.use('*', loggingMiddleware);
+ * Tentickle.telemetryProvider = myProvider;
+ *
+ * // createApp and run use Tentickle
+ * const app = createApp(MyAgent, { model });
+ * const result = await run(<MyAgent />, { messages, model });
+ *
+ * // Create scoped instance with its own middleware
+ * const scoped = Tentickle.create();
+ * scoped.use('model:generate', specialMiddleware);
+ * const scopedResult = await scoped.run(<MyAgent />, { messages, model });
+ * ```
+ */
+export declare const Tentickle: TentickleInstance;
+/**
+ * Create an app from a component function.
+ *
+ * This is `Tentickle.createApp` - apps inherit middleware from the global Tentickle instance.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from 'tentickle';
+ *
+ * const app = createApp(MyAgent, { model });
+ * const result = await app.run({ props: { query: "Hello!" } });
+ * ```
+ */
+export declare const createApp: <P extends Record<string, unknown>>(Component: ComponentFunction<P>, options?: AppOptions) => App<P>;
+/**
+ * One-shot execution of a JSX component.
+ *
+ * This is `Tentickle.run` - the simplest way to run an agent.
+ * Returns SessionExecutionHandle (AsyncIterable, not PromiseLike).
+ *
+ * @example
+ * ```typescript
+ * import { run } from 'tentickle';
+ *
+ * // Get result
+ * const result = await run(<MyAgent />, { messages, model }).result;
+ *
+ * // Stream events
+ * const handle = await run(<MyAgent />, { messages, model });
+ * for await (const event of handle) {
+ *   console.log(event);
+ * }
+ * ```
+ */
+export declare const run: Procedure<RunHandler, true>;
+export {};
+//# sourceMappingURL=tentickle-instance.d.ts.map

package/dist/tentickle-instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tentickle-instance.d.ts","sourceRoot":"","sources":["../src/tentickle-instance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,iBAAiB,EAEtB,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,GAAG,EACH,QAAQ,EACR,UAAU,EAGV,sBAAsB,EACtB,iBAAiB,EAGlB,MAAM,aAAa,CAAC;AAGrB;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC;CACvD;AA8fD;;;GAGG;AACH,KAAK,UAAU,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,OAAO,EAAE;IAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,EAC9E,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,KAChB,sBAAsB,CAAC;AAE5B;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,OAAO,CAAC,kBAAkB,CAA0C;IACpE,OAAO,CAAC,kBAAkB,CAAC,CAAoB;IAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAE1C;;OAEG;gBACS,OAAO,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;KAAE;IA+B/D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,GAAG,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI;IAM1D;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,EAAE;IAsBrD;;;OAGG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,iBAAiB,IAAI,iBAAiB,GAAG,SAAS,CAErD;IAED;;OAEG;IACH,IAAI,iBAAiB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EAE5D;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,OAAO,GAAE,8BAAmC,GAAG,iBAAiB;IAevE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC/B,OAAO,GAAE,UAAe,GACvB,GAAG,CAAC,CAAC,CAAC;CAKV;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,SAAS,mBAA0B,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,GAjDV,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aAC9B,iBAAiB,CAAC,CAAC,CAAC,YACtB,UAAU,KAClB,GAAG,CAAC,CAAC,CA8CkD,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,GAAG,6BAAgC,CAAC"}