@namzu/sdk 0.1.4 → 0.1.5-rc.1

package/src/agents/AbstractAgent.ts

@@ -1,4 +1,4 @@
-import type { AgentManager } from '../manager/agent/lifecycle.js'
+import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
 import type {
 	Agent,
 	AgentCapabilities,
@@ -8,13 +8,14 @@ import type {
 	BaseAgentConfig,
 	BaseAgentResult,
 } from '../types/agent/index.js'
-import { EMPTY_TOKEN_USAGE } from '../types/common/index.js'
+import type { AgentManagerContract } from '../types/agent/manager.js'
 import type { RunId } from '../types/ids/index.js'
 import type { RunEvent, RunEventListener } from '../types/run/index.js'
 import { ZERO_COST } from '../utils/cost.js'
 import { toErrorMessage } from '../utils/error.js'
 import { generateRunId } from '../utils/id.js'
 import { type Logger, getRootLogger } from '../utils/logger.js'
+import { InvocationLock } from './lock.js'
 
 export abstract class AbstractAgent<
 	TConfig extends BaseAgentConfig = BaseAgentConfig,
@@ -25,14 +26,16 @@ export abstract class AbstractAgent<
 	readonly metadata: AgentMetadata
 	protected log: Logger
 	protected abortController: AbortController
+	private readonly invocationLock: InvocationLock
 
-	protected agentManager?: AgentManager
+	protected agentManager?: AgentManagerContract
 
 	protected currentRunId?: RunId
 
 	constructor(metadata: AgentMetadata) {
 		this.metadata = metadata
 		this.abortController = new AbortController()
+		this.invocationLock = new InvocationLock()
 		this.log = getRootLogger().child({
 			component: `Agent:${metadata.type}`,
 			agentId: metadata.id,
@@ -41,6 +44,26 @@ export abstract class AbstractAgent<
 
 	abstract run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult>
 
+	/**
+	 * Acquire the invocation lock to prevent concurrent execution.
+	 * Returns a Disposable that must be disposed to release the lock.
+	 *
+	 * Usage:
+	 * ```typescript
+	 * const lock = this.acquireInvocationLock()
+	 * try {
+	 *   // do work
+	 * } finally {
+	 *   lock[Symbol.dispose]()
+	 * }
+	 * ```
+	 *
+	 * @throws {ConcurrentInvocationError} if the agent is already executing
+	 */
+	protected acquireInvocationLock() {
+		return this.invocationLock.acquire(this.metadata.id)
+	}
+
 	async cancel(): Promise<void> {
 		this.abortController.abort()
 

package/src/agents/PipelineAgent.ts

@@ -1,3 +1,4 @@
+import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
 import type {
 	AgentInput,
 	AgentMetadata,
@@ -6,7 +7,6 @@ import type {
 	PipelineStepResult,
 	StepContext,
 } from '../types/agent/index.js'
-import { EMPTY_TOKEN_USAGE } from '../types/common/index.js'
 import type { RunEventListener } from '../types/run/index.js'
 import { ZERO_COST } from '../utils/cost.js'
 import { toErrorMessage } from '../utils/error.js'

package/src/agents/ReactiveAgent.ts

@@ -67,6 +67,7 @@ export class ReactiveAgent extends AbstractAgent<ReactiveAgentConfig, ReactiveAg
 				taskStore: input.taskStore,
 				runtimeToolOverrides: input.runtimeToolOverrides,
 				advisory: config.advisory,
+				invocationState: config.invocationState,
 			},
 			listener,
 		)

package/src/agents/RouterAgent.ts

@@ -1,3 +1,4 @@
+import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
 import { FallbackResolver } from '../runtime/decision/fallback.js'
 import { DecisionParser } from '../runtime/decision/parser.js'
 import type {
@@ -7,8 +8,8 @@ import type {
 	RouterAgentResult,
 	RoutingDecision,
 } from '../types/agent/index.js'
-import { EMPTY_TOKEN_USAGE } from '../types/common/index.js'
 import type { FallbackStrategy } from '../types/decision/index.js'
+import { deriveChildState } from '../types/invocation/index.js'
 import { createSystemMessage, createUserMessage } from '../types/message/index.js'
 import type { RunEventListener } from '../types/run/index.js'
 import { ZERO_COST } from '../utils/cost.js'
@@ -83,7 +84,12 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 			targetRoute = fallback
 		}
 
-		const delegateResult = await targetRoute.agent.run(input, config, listener)
+		const childInvocationState = deriveChildState(config.invocationState, this.metadata.id)
+		const delegateResult = await targetRoute.agent.run(
+			input,
+			{ ...config, invocationState: childInvocationState },
+			listener,
+		)
 
 		await this.emitEvent(
 			{

package/src/agents/SupervisorAgent.ts

@@ -1,3 +1,4 @@
+import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
 import { LocalTaskGateway } from '../gateway/local.js'
 import { ToolRegistry } from '../registry/tool/execute.js'
 import { drainQuery } from '../runtime/query/index.js'
@@ -11,8 +12,8 @@ import type {
 	SupervisorAgentResult,
 } from '../types/agent/index.js'
 import type { AgentTaskContext } from '../types/agent/task.js'
-import { EMPTY_TOKEN_USAGE } from '../types/common/index.js'
 import type { TaskId, ThreadId } from '../types/ids/index.js'
+import { deriveChildState } from '../types/invocation/index.js'
 import type { RunEventListener } from '../types/run/index.js'
 import { ZERO_COST } from '../utils/cost.js'
 import { AbstractAgent } from './AbstractAgent.js'
@@ -98,6 +99,8 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 			tools.register(tool)
 		}
 
+		const childInvocationState = deriveChildState(config.invocationState, this.metadata.id)
+
 		const run = await drainQuery(
 			{
 				systemPrompt: config.systemPrompt,
@@ -129,6 +132,7 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				taskGateway: gateway,
 				launchedTasks,
 				advisory: config.advisory,
+				invocationState: childInvocationState,
 			},
 			listener,
 		)

package/src/agents/__tests__/lock.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest'
+import { ConcurrentInvocationError, InvocationLock } from '../lock.js'
+
+describe('InvocationLock', () => {
+	describe('acquire', () => {
+		it('should acquire lock when not locked', () => {
+			const lock = new InvocationLock()
+			const agentId = 'agent-123'
+
+			const disposable = lock.acquire(agentId)
+
+			expect(disposable).toBeDefined()
+			expect(disposable[Symbol.dispose]).toBeDefined()
+			expect(lock.isActive()).toBe(true)
+		})
+
+		it('should throw ConcurrentInvocationError when already locked', () => {
+			const lock = new InvocationLock()
+			const agentId = 'agent-123'
+
+			lock.acquire(agentId)
+
+			expect(() => lock.acquire(agentId)).toThrow(ConcurrentInvocationError)
+		})
+
+		it('should throw with correct agent ID in error', () => {
+			const lock = new InvocationLock()
+			const agentId = 'agent-456'
+
+			lock.acquire(agentId)
+
+			try {
+				lock.acquire(agentId)
+				expect.fail('Should have thrown ConcurrentInvocationError')
+			} catch (err) {
+				if (err instanceof ConcurrentInvocationError) {
+					expect(err.agentId).toBe(agentId)
+					expect(err.message).toContain(agentId)
+				} else {
+					throw err
+				}
+			}
+		})
+	})
+
+	describe('dispose', () => {
+		it('should release lock when disposed', () => {
+			const lock = new InvocationLock()
+			const agentId = 'agent-123'
+
+			const disposable = lock.acquire(agentId)
+			expect(lock.isActive()).toBe(true)
+
+			disposable[Symbol.dispose]()
+			expect(lock.isActive()).toBe(false)
+		})
+
+		it('should allow re-acquisition after disposal', () => {
+			const lock = new InvocationLock()
+			const agentId = 'agent-123'
+
+			const disposable1 = lock.acquire(agentId)
+			disposable1[Symbol.dispose]()
+
+			// Should not throw
+			const disposable2 = lock.acquire(agentId)
+			expect(disposable2).toBeDefined()
+			expect(lock.isActive()).toBe(true)
+
+			disposable2[Symbol.dispose]()
+		})
+	})
+
+	describe('isActive', () => {
+		it('should return false when not locked', () => {
+			const lock = new InvocationLock()
+			expect(lock.isActive()).toBe(false)
+		})
+
+		it('should return true when locked', () => {
+			const lock = new InvocationLock()
+			lock.acquire('agent-123')
+			expect(lock.isActive()).toBe(true)
+		})
+
+		it('should return false after disposal', () => {
+			const lock = new InvocationLock()
+			const disposable = lock.acquire('agent-123')
+			expect(lock.isActive()).toBe(true)
+
+			disposable[Symbol.dispose]()
+			expect(lock.isActive()).toBe(false)
+		})
+	})
+
+	describe('try/finally pattern', () => {
+		it('should release lock in finally block', () => {
+			const lock = new InvocationLock()
+			const agentId = 'agent-123'
+
+			const disposable = lock.acquire(agentId)
+			try {
+				expect(lock.isActive()).toBe(true)
+			} finally {
+				disposable[Symbol.dispose]()
+			}
+
+			expect(lock.isActive()).toBe(false)
+		})
+
+		it('should release lock even if error thrown', () => {
+			const lock = new InvocationLock()
+			const agentId = 'agent-123'
+
+			const disposable = lock.acquire(agentId)
+			try {
+				throw new Error('Test error')
+			} catch {
+				disposable[Symbol.dispose]()
+			}
+
+			expect(lock.isActive()).toBe(false)
+
+			// Should be able to acquire again
+			const disposable2 = lock.acquire(agentId)
+			expect(disposable2).toBeDefined()
+		})
+	})
+})
+
+describe('ConcurrentInvocationError', () => {
+	it('should be an instance of Error', () => {
+		const error = new ConcurrentInvocationError('agent-123')
+		expect(error).toBeInstanceOf(Error)
+	})
+
+	it('should have correct name', () => {
+		const error = new ConcurrentInvocationError('agent-123')
+		expect(error.name).toBe('ConcurrentInvocationError')
+	})
+
+	it('should store agentId', () => {
+		const agentId = 'agent-abc'
+		const error = new ConcurrentInvocationError(agentId)
+		expect(error.agentId).toBe(agentId)
+	})
+
+	it('should include agent ID in message', () => {
+		const agentId = 'agent-xyz'
+		const error = new ConcurrentInvocationError(agentId)
+		expect(error.message).toContain(agentId)
+	})
+
+	it('should mention concurrent invocations in message', () => {
+		const error = new ConcurrentInvocationError('agent-123')
+		expect(error.message.toLowerCase()).toContain('concurrent')
+	})
+})

package/src/agents/index.ts

@@ -5,3 +5,5 @@ export { RouterAgent } from './RouterAgent.js'
 export { SupervisorAgent } from './SupervisorAgent.js'
 export { defineAgent } from './defineAgent.js'
 export type { DefineAgentOptions } from './defineAgent.js'
+export { InvocationLock, ConcurrentInvocationError } from './lock.js'
+export type { ConcurrencyMode, Disposable } from './lock.js'

package/src/agents/lock.ts

@@ -0,0 +1,66 @@
+/**
+ * Invocation lock to prevent concurrent execution of the same agent instance.
+ * Uses a simple boolean flag with RAII-style cleanup via Disposable pattern.
+ */
+
+export type ConcurrencyMode = 'throw' | 'queue'
+
+export interface Disposable {
+	[Symbol.dispose](): void
+}
+
+export class ConcurrentInvocationError extends Error {
+	readonly agentId: string
+
+	constructor(agentId: string) {
+		super(`Agent ${agentId} is already processing. Concurrent invocations are not allowed.`)
+		this.name = 'ConcurrentInvocationError'
+		this.agentId = agentId
+	}
+}
+
+/**
+ * Simple lock mechanism to prevent concurrent invocations of the same agent.
+ *
+ * When the lock is acquired:
+ * - Returns a Disposable object that releases the lock when disposed
+ * - If already locked, throws ConcurrentInvocationError
+ *
+ * Usage with try/finally:
+ * ```
+ * const lock = this.invocationLock.acquire(agentId)
+ * try {
+ *   // do work
+ * } finally {
+ *   lock[Symbol.dispose]()
+ * }
+ * ```
+ */
+export class InvocationLock {
+	private isLocked = false
+
+	/**
+	 * Acquire the lock. Returns a Disposable that releases the lock when disposed.
+	 * @throws {ConcurrentInvocationError} if the lock is already held
+	 */
+	acquire(agentId: string): Disposable {
+		if (this.isLocked) {
+			throw new ConcurrentInvocationError(agentId)
+		}
+
+		this.isLocked = true
+
+		return {
+			[Symbol.dispose]: () => {
+				this.isLocked = false
+			},
+		}
+	}
+
+	/**
+	 * Check if the lock is currently active (held).
+	 */
+	isActive(): boolean {
+		return this.isLocked
+	}
+}

package/src/bridge/a2a/message.ts

@@ -1,7 +1,6 @@
 import type { ThreadMessage } from '../../contracts/index.js'
 import type { A2AMessage, A2AMessageRole, A2APart, TextPart } from '../../types/a2a/index.js'
-import type { MessageRole } from '../../types/message/index.js'
-import type { Message } from '../../types/message/index.js'
+import type { Message, MessageRole } from '../../types/message/index.js'
 
 function toA2ARole(role: MessageRole): A2AMessageRole {
 	switch (role) {

package/src/bridge/tools/connector/router.ts

@@ -1,6 +1,5 @@
 import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
-import type { ToolRegistry } from '../../../registry/tool/execute.js'
-import type { ToolDefinition } from '../../../types/tool/index.js'
+import type { ToolDefinition, ToolRegistryContract } from '../../../types/tool/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
 import { type Logger, getRootLogger } from '../../../utils/logger.js'
 import { connectorInstanceToTools, createConnectorRouterTool } from './adapter.js'
@@ -43,7 +42,7 @@ export class ConnectorToolRouter {
 		return tools
 	}
 
-	registerTools(toolRegistry: ToolRegistry): string[] {
+	registerTools(toolRegistry: ToolRegistryContract): string[] {
 		const tools = this.getTools()
 		const names: string[] = []
 		for (const tool of tools) {
@@ -54,14 +53,14 @@ export class ConnectorToolRouter {
 		return names
 	}
 
-	unregisterTools(toolRegistry: ToolRegistry, toolNames: string[]): void {
+	unregisterTools(toolRegistry: ToolRegistryContract, toolNames: string[]): void {
 		for (const name of toolNames) {
 			toolRegistry.unregister(name)
 		}
 		this.log.info(`Unregistered ${toolNames.length} connector tools`)
 	}
 
-	refreshTools(toolRegistry: ToolRegistry, previousNames: string[]): string[] {
+	refreshTools(toolRegistry: ToolRegistryContract, previousNames: string[]): string[] {
 		this.unregisterTools(toolRegistry, previousNames)
 		return this.registerTools(toolRegistry)
 	}

package/src/compaction/__tests__/SlidingWindowManager.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest'
+import {
+	createAssistantMessage,
+	createToolMessage,
+	createUserMessage,
+} from '../../types/message/index.js'
+import { SlidingWindowManager } from '../managers/slidingWindow.js'
+
+describe('SlidingWindowManager', () => {
+	it('should have correct name', () => {
+		const manager = new SlidingWindowManager()
+		expect(manager.name).toBe('sliding-window')
+	})
+
+	it('should not trim messages under window size', () => {
+		const manager = new SlidingWindowManager({ keepRecentMessages: 4 })
+		const messages = [
+			createUserMessage('msg 1'),
+			createAssistantMessage('response 1'),
+			createUserMessage('msg 2'),
+		]
+
+		const result = manager.applyManagement(messages)
+		expect(result).toHaveLength(3)
+	})
+
+	it('should trim messages exceeding window size', () => {
+		const manager = new SlidingWindowManager({ keepRecentMessages: 2 })
+		const messages = [
+			createUserMessage('msg 1'),
+			createAssistantMessage('response 1'),
+			createUserMessage('msg 2'),
+			createAssistantMessage('response 2'),
+			createUserMessage('msg 3'),
+			createAssistantMessage('response 3'),
+		]
+
+		const result = manager.applyManagement(messages)
+		expect(result.length).toBeLessThanOrEqual(messages.length)
+		expect(result.length).toBeGreaterThanOrEqual(2)
+	})
+
+	it('should preserve recent messages', () => {
+		const manager = new SlidingWindowManager({ keepRecentMessages: 2 })
+		const msg1 = createUserMessage('msg 1')
+		const msg2 = createAssistantMessage('response 1')
+		const msg3 = createUserMessage('msg 2')
+		const msg4 = createAssistantMessage('response 2')
+
+		const messages = [msg1, msg2, msg3, msg4]
+		const result = manager.applyManagement(messages)
+
+		// Should include the most recent messages
+		expect(result).toContain(msg3)
+		expect(result).toContain(msg4)
+	})
+
+	it('should preserve tool call/result pairs', () => {
+		const manager = new SlidingWindowManager({ keepRecentMessages: 2 })
+		const messages = [
+			createUserMessage('old message'),
+			createAssistantMessage(null, [
+				{
+					id: 'call_1',
+					type: 'function',
+					function: { name: 'test_tool', arguments: '{}' },
+				},
+			]),
+			createToolMessage('result 1', 'call_1'),
+			createUserMessage('recent message'),
+		]
+
+		const result = manager.applyManagement(messages)
+
+		// Should keep the tool call/result pair together if included
+		const callIdx = result.findIndex(
+			(m) => m.role === 'assistant' && 'toolCalls' in m && m.toolCalls?.length === 1,
+		)
+		const resultIdx = result.findIndex(
+			(m) => m.role === 'tool' && 'toolCallId' in m && m.toolCallId === 'call_1',
+		)
+
+		if (callIdx !== -1) {
+			// If call is present, result should be present and after it
+			expect(resultIdx).toBeGreaterThan(callIdx)
+		} else {
+			// If call is removed, result should also be removed
+			expect(resultIdx).toBe(-1)
+		}
+	})
+
+	it('should return false from reduceContext if already minimal', () => {
+		const manager = new SlidingWindowManager({ keepRecentMessages: 1 })
+		const messages = [createUserMessage('msg')]
+
+		const result = manager.reduceContext(messages, 1000)
+		expect(result).toBe(false)
+	})
+
+	it('should return true from reduceContext if reduction possible', () => {
+		const manager = new SlidingWindowManager({ keepRecentMessages: 4 })
+		const messages = [
+			createUserMessage('msg 1'),
+			createAssistantMessage('response 1'),
+			createUserMessage('msg 2'),
+			createAssistantMessage('response 2'),
+			createUserMessage('msg 3'),
+			createAssistantMessage('response 3'),
+			createUserMessage('msg 4'),
+			createAssistantMessage('response 4'),
+		]
+
+		const result = manager.reduceContext(messages, 1000)
+		expect(result).toBe(true)
+	})
+
+	it('should use default keepRecentMessages when not provided', () => {
+		const manager = new SlidingWindowManager()
+		const messages = Array(10)
+			.fill(null)
+			.map((_, i) => createUserMessage(`msg ${i}`))
+
+		const result = manager.applyManagement(messages)
+		expect(result.length).toBeLessThanOrEqual(4) // default is 4
+	})
+
+	it('should handle empty message array', () => {
+		const manager = new SlidingWindowManager()
+		const result = manager.applyManagement([])
+		expect(result).toHaveLength(0)
+	})
+
+	it('should handle single message', () => {
+		const manager = new SlidingWindowManager({ keepRecentMessages: 2 })
+		const messages = [createUserMessage('only message')]
+		const result = manager.applyManagement(messages)
+		expect(result).toEqual(messages)
+	})
+})