Session config

BaseSessionConfig is the minimum a config needs to drive buildSessionOptions(). Your agent extends it with whatever its domain needs; the kit only reads its own fields, and passes the whole object to your AgentSpec methods.

import type { BaseSessionConfig } from "@falkenslab/agent-kit";

interface Config extends BaseSessionConfig {
  courseUrl: string;
  password: string;
}

Fields

Field	Type	Required	What it does
mode	"interactive" | "guided" | "autonomous"	yes	How much a human is in the loop. See Modes.
projectDir	string	yes	The project root: the session's working directory when the agent has file tools or plugins, and the base for relative paths in the file scope.
knowledgeDir	string	no	The agent's notes. Gives the session the file tools and, by default, the knowledge base.
sourcesDir	string	no	Originals, kept as obtained: readable and searchable, never writable. Gives the file tools and the save_to_sources tool.
extraWritableDirs	string[]	no	More folders where Write/Edit are allowed (and Grep searches).
deniedPaths	string[]	no	Files or folders the agent must never read, search or write, e.g. a config file holding a password.
secrets	string[]	no	Values scrubbed from the transcript log, e.g. a password.
language	string	no	The language of the kit's texts and of the agent's replies ("en", "es", "fr", "de"). --language on the command line wins over it.

Examples

A chat with no files

const config: BaseSessionConfig = { mode: "autonomous", projectDir: process.cwd() };

No knowledgeDir and no sourcesDir: the agent gets no file tools at all.

Notes and originals

const workspace = path.resolve(process.argv[2] ?? ".");

const config: BaseSessionConfig = {
  mode: "guided",
  projectDir: workspace,
  knowledgeDir: path.join(workspace, "knowledge"),
  sourcesDir: path.join(workspace, "sources"),
};

The agent can read everything under workspace that isn't denied, write only inside knowledge/, search inside knowledge/ and sources/, and add to sources/ only through save_to_sources.

Protecting a secret

interface Config extends BaseSessionConfig {
  password: string;
}

const configFile = path.join(workspace, "agent.config.json");
const { password } = JSON.parse(await readFile(configFile, "utf8"));

const config: Config = {
  mode: "guided",
  projectDir: workspace,
  knowledgeDir: path.join(workspace, "knowledge"),
  deniedPaths: [configFile], // never readable, searchable or writable
  secrets: [password], // never written to transcript.jsonl in clear
  password,
};

deniedPaths is enforced by the file scope hook; secrets by the transcript logger. Use both: one keeps the agent from reading the file, the other keeps the value out of the log if it ever reaches a tool call another way (the agent typing it into a login form, say).

Extra writable folders

const config: BaseSessionConfig = {
  mode: "guided",
  projectDir: workspace,
  knowledgeDir: path.join(workspace, "knowledge"),
  extraWritableDirs: [path.join(workspace, "drafts")],
};

Forcing a language

const config: BaseSessionConfig = { mode: "guided", projectDir: workspace, language: "fr" };

The person running the agent can still override it with --language=de. See Languages.

Mode is not "chat vs one-shot"

mode is only about supervision. Whether a session is a multi-turn chat or a one-shot run depends on how you start it (runChatInk() or runQuery() with a string). If your agent needs to know it's in a chat (to pick a different prompt, say), add your own field to the config.