interface-implementation
Add a built-in implementation of an interface in OtterAgent. Use when implementing a new built-in for an existing interface (e.g. a new SessionManager, AuthStorage, or UIProvider).
- License 许可
- MIT
- 最近更新
- 2026-04-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- interface-implementation
- description
- Add a built-in implementation of an interface in OtterAgent. Use when implementing a new built-in for an existing interface (e.g. a new SessionManager, AuthStorage, or UIProvider).
03 SKILL.md 正文
Follow this pattern exactly when adding a built-in implementation of an OtterAgent interface.
Folder Structure
Implementations of a given interface live together in a dedicated folder:
src/
<interface-name-plural>/ e.g. session-managers/, auth-storages/
<impl-name>.ts e.g. in-memory-session-manager.ts
<impl-name>.test.ts e.g. in-memory-session-manager.test.ts
index.ts namespace + re-exports for the whole folder
If the folder already exists (other implementations are present), add the new .ts and .test.ts files alongside them and add the new factory to the existing index.ts namespace.
1. Implementation File (<impl-name>.ts)
- Define the implementation as an exported class.
- Export a
createXxx()factory function as a convenience wrapper. - The class must explicitly
implementsthe interface so TypeScript enforces completeness.
// src/session-managers/in-memory-session-manager.ts
import type { SessionManager } from "../interfaces/session-manager.js";
export class InMemorySessionManager implements SessionManager {
// ... implementation
}
/**
* Creates an in-memory {@link SessionManager} with no filesystem persistence.
*/
export function createInMemorySessionManager(): InMemorySessionManager {
return new InMemorySessionManager();
}
2. Namespace / Index File (index.ts)
This file does three things:
- Re-exports the class and factory function(s) from implementation files.
- Declares a namespace whose name matches the interface, merged with an empty interface extension. This makes the interface name serve as both a type and a value (the namespace) from a single import.
// src/session-managers/index.ts
import type { SessionManager as ISessionManager } from "../interfaces/session-manager.js";
import { createInMemorySessionManager, InMemorySessionManager } from "./in-memory-session-manager.js";
export { createInMemorySessionManager, InMemorySessionManager } from "./in-memory-session-manager.js";
// Empty interface extension enables TypeScript declaration merging with the
// namespace below. Consumers get SessionManager as both a type and a value.
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface SessionManager extends ISessionManager {}
// eslint-disable-next-line @typescript-eslint/no-namespace
export namespace SessionManager {
export function inMemory(): InMemorySessionManager {
return createInMemorySessionManager();
}
// Add new built-ins here as additional methods on the same namespace.
// export function sqlite(path: string): SqliteSessionManager { ... }
}
Why the empty interface? TypeScript does not allow merging a namespace with a plain type alias or an imported interface re-export. The empty interface Xxx extends IXxx {} declares a local interface that TypeScript can merge with the namespace in the same file.
3. Root Barrel (src/index.ts)
Export the class and namespace from the implementations index. A single export { Xxx } is enough for the namespace — TypeScript carries both the type (via the merged interface) and the value (the namespace) through one export. The class gets its own named export alongside.
Do NOT also add a separate export type { Xxx } for the same name — this causes TS2300: Duplicate identifier.
// src/index.ts
// Remove the interface from the plain type export block if it was there:
export type {
AgentEnvironment,
AuthStorage,
// SessionManager, ← moved to session-managers export below
ToolDefinition,
UIProvider,
} from "./interfaces/index.js";
// Add the namespace export (carries both type and factory value)
// and the class export:
export {
InMemorySessionManager,
createInMemorySessionManager,
SessionManager,
} from "./session-managers/index.js";
If the interface was previously exported as export type { Xxx } from interfaces/index.js, remove it from that block and replace it with the single export { Xxx } from the implementations folder.
4. Consumer Usage
After wiring, consumers get a clean API with a single import:
import { SessionManager, InMemorySessionManager } from "@otter-agent/core";
// As a type:
function accepts(sm: SessionManager) { ... }
// As a factory (recommended convenience API):
const sm = SessionManager.inMemory();
// Direct class construction (for subclassing, instanceof, or impl-specific APIs):
const sm = new InMemorySessionManager();
Both the namespace factory and direct construction produce the same class instance, so instanceof works regardless of how the instance was created:
const sm1 = SessionManager.inMemory();
const sm2 = createInMemorySessionManager();
const sm3 = new InMemorySessionManager();
sm1 instanceof InMemorySessionManager; // true
sm2 instanceof InMemorySessionManager; // true
sm3 instanceof InMemorySessionManager; // true
5. Tests
Place tests in <impl-name>.test.ts alongside the implementation. Tests should be comprehensive and cover:
- Every interface method: returns a unique
EntryId, correct data stored/excluded buildSessionContext()(or equivalent read method): correct output for all scenarios- Edge cases specific to the implementation
- The namespace factory method (e.g.
SessionManager.inMemory()) produces a working, independent instance - Direct class construction via
newproduces a working instance instanceofchecks pass for all creation paths (direct, factory, namespace)
Reference Implementation
See src/session-managers/ for the canonical worked example:
in-memory-session-manager.ts— exported class + factoryindex.ts— namespace merging + class re-exportin-memory-session-manager.test.ts— tests covering all interface methods, edge cases, factory, direct construction, and instanceof
04 同仓库更多 Skills
overview
Overview of the repository, core components, and open GitHub issues
interface-implementation
Add a built-in implementation of an interface in OtterAgent. Use when implementing a new built-in for an existing interface (e.g. a new SessionManager, AuthStorage, or UIProvider).
code-review
Run an independent code review using pi-coding-agent. Use after completing an implementation to get a second opinion before pushing. Pass the issue number or a short description of what was implemented.