@tabbybyte/kimten 0.2.0 → 0.3.0

package/README.md

@@ -99,7 +99,7 @@ cat.forget();
 
 ---
 
-## 🧠 Mental Model
+## 💭 Mental Model
 
 Kimten is basically:
 
@@ -125,15 +125,15 @@ Each instance keeps short-term chat memory, so follow-up prompts naturally refer
 Create a new instance.
 
 #### Required
-* `brain` → AI SDK model instance
+* 🧠 `brain` → AI SDK model instance
 
 #### Optional
 
-* `toys` → object map of toy (tool) definitions. Each entry is:
+* 🎱 `toys` → object map of toy (tool) definitions. Each entry is:
   * object form: `{ inputSchema?, description?, strict?, execute }`
   default: `{}`
-* `personality` → system instructions / prompt for overall behavior description (default: `'You are a helpful assistant.'`)
-* `hops` → max agent loop steps (default: `10`) - prevents infinite zoomies 🌀
+* 🕵️‍♂️ `personality` → system instructions / prompt for overall behavior description (default: `'You are a helpful assistant.'`)
+* 🌀 `hops` → max agent loop steps (default: `10`) - prevents infinite zoomies
 
 #### Toy semantics
 
@@ -144,15 +144,17 @@ Create a new instance.
 
 #### Returns
 
-* `play(input, schema?)`
+* `play(input, schema?, context?)`
 
   * runs the agent  
   * uses short-term memory automatically  
   * optional Zod schema for structured output
+  * optional plain object context injected into the current call prompt as JSON (with basic redaction/truncation guards)
+  * context is ephemeral per `play()` call and is not persisted in memory
 
 * `forget()`
 
-  * clears short-term memory/context
+  * clears short-term memory
 
 ---
 
@@ -164,7 +166,7 @@ For the `brain` part, feel free to use any compatible provider and their models.
 
 ❗ Note that not all providers (and models) may work out the box with Kimten, particularly for structured output.
 
-💡 Refer to the AI SDK docs: **[providers and models](https://ai-sdk.dev/docs/foundations/providers-and-models)**.
+💡 Refer to the AI SDK docs for details: **[providers and models](https://ai-sdk.dev/docs/foundations/providers-and-models)**.
 
 ### Add toys freely
 

package/index.d.ts

@@ -21,8 +21,12 @@ export type KimtenConfig = {
 };
 
 export type KimtenAgent = {
-  play(input: string): Promise<string>;
-  play<S extends ZodTypeAny>(input: string, schema: S): Promise<ZodInfer<S>>;
+  play(input: string, schema?: null, context?: Record<string, unknown> | null): Promise<string>;
+  play<S extends ZodTypeAny>(
+    input: string,
+    schema: S,
+    context?: Record<string, unknown> | null
+  ): Promise<ZodInfer<S>>;
   forget(): void;
 };
 

package/lib/kimten.js

@@ -3,6 +3,7 @@ import { createMemory } from './memory.js';
 import { normalizeToys } from './tools.js';
 
 const DEFAULT_PERSONALITY = 'You are a helpful assistant.';
+const CONTEXT_CHAR_LIMIT = 4000;
 
 /**
  * @typedef {import('zod').ZodTypeAny} ZodSchema
@@ -59,7 +60,7 @@ const DEFAULT_PERSONALITY = 'You are a helpful assistant.';
  * Returned Kimten instance.
  *
  * @typedef {object} KimtenAgent
- * @property {(input: string, schema?: ZodSchema | null) => Promise<any>} play Run the agent loop.
+ * @property {(input: string, schema?: ZodSchema | null, context?: Record<string, unknown> | null) => Promise<any>} play Run the agent loop.
  * @property {() => void} forget Clear short-term memory.
  */
 
@@ -91,6 +92,45 @@ function validateConfig(config) {
   };
 }
 
+function serializeContext(context) {
+  if (context === null || context === undefined) {
+    return '';
+  }
+
+  if (typeof context !== 'object' || Array.isArray(context)) {
+    throw new TypeError('Kimten play(input, schema, context) expects context to be a plain object when provided.');
+  }
+
+  const redacted = JSON.stringify(
+    context,
+    (key, value) => {
+      const lowered = String(key).toLowerCase();
+      if (
+        lowered.includes('password') ||
+        lowered.includes('token') ||
+        lowered.includes('secret') ||
+        lowered.includes('apikey') ||
+        lowered.includes('api_key')
+      ) {
+        return '[REDACTED]';
+      }
+
+      return value;
+    },
+    2
+  );
+
+  if (typeof redacted !== 'string') {
+    return '';
+  }
+
+  if (redacted.length <= CONTEXT_CHAR_LIMIT) {
+    return redacted;
+  }
+
+  return `${redacted.slice(0, CONTEXT_CHAR_LIMIT)}\n...(truncated)`;
+}
+
 /**
  * Create a tiny tool-using agent with short-term memory.
  *
@@ -143,19 +183,41 @@ export function Kimten(config) {
    *
    * @param {string} input
    * @param {ZodSchema | null} [schema]
+   * @param {Record<string, unknown> | null} [context]
    * @returns {Promise<any>}
    */
-  async function play(input, schema = null) {
+  async function play(input, schema = null, context = null) {
     if (typeof input !== 'string') {
       throw new TypeError('Kimten play(input) expects input to be a string.');
     }
 
+    // Serialize provided context (redacts sensitive keys and truncates if too long).
+    const serializedContext = serializeContext(context);
+
+    // If we have context, embed it before the user's message so the agent sees both.
+    const effectiveInput = serializedContext
+      ? `Context (JSON):\n${serializedContext}\n\nUser message:\n${input}`
+      : input;
+
+    // Store the raw user message (no context) in short-term memory.
     memory.add({ role: 'user', content: input });
 
+    // Retrieve conversation so far from memory.
+    const fetchedMessages = memory.list();
+
+    // If the last message is the user message we just added, we may need to replace it with
+    // a version that includes the serialized context, so the agent can see that information.
+    // This way we keep the raw user message in memory, but provide the agent with the enriched version.
+    const lastMessage = fetchedMessages[fetchedMessages.length - 1];
+    const messages = serializedContext && lastMessage?.role === 'user'
+      ? [...fetchedMessages.slice(0, -1), { ...lastMessage, content: effectiveInput }]
+      : fetchedMessages;
+
+    // Choose a structured agent when a schema is provided, otherwise use the text agent.
     const agent = schema ? getStructuredAgent(schema) : textAgent;
-    const result = await agent.generate({
-      messages: memory.list(),
-    });
+
+    // Run the agent loop with the prepared messages.
+    const result = await agent.generate({ messages });
 
     const assistantContent =
       schema

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabbybyte/kimten",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },