What causes "invalid Agent session ID" in siyuan-note/siyuan?

Generate session IDs in the SiYuan node-ID format (YYYYMMDDhhmmss-abcdefg style accepted by ast.IsNodeIDPattern)

invalid Agent session ID

Error message

invalid Agent session ID

What it means

SaveAgentTodos persists an AI-agent todo list under data/storage/ai/agent/sessions/<sessionID>/todos.json. The sessionID is interpolated into a filesystem path, so the kernel validates it against ast.IsNodeIDPattern (the SiYuan node-ID format) before touching disk. A session ID not matching that pattern is rejected to prevent path traversal or writing into unexpected directories.

Source

Thrown at kernel/model/todo.go:46

)

type AgentTodoItem struct {
	Content string `json:"content"`
	Status  string `json:"status"` // pending, in_progress, completed, cancelled
}

type AgentTodoList struct {
	SessionID string          `json:"sessionID"`
	Todos     []AgentTodoItem `json:"todos"`
}

func agentTodosPath(sessionID string) string {
	return filepath.Join(util.DataDir, "storage", "ai", "agent", "sessions", sessionID, "todos.json")
}

func SaveAgentTodos(sessionID string, todos []AgentTodoItem) error {
	if !ast.IsNodeIDPattern(sessionID) {
		return errors.New("invalid Agent session ID")
	}
	dir := filepath.Join(util.DataDir, "storage", "ai", "agent", "sessions", sessionID)
	if err := os.MkdirAll(dir, 0755); err != nil {
		return err
	}

	data := AgentTodoList{
		SessionID: sessionID,
		Todos:     todos,
	}

	b, err := json.Marshal(data)
	if err != nil {
		return err
	}

	return filelock.WriteFile(agentTodosPath(sessionID), b)
}

View on GitHub (pinned to 8641553a1f)

Solutions

Generate session IDs in the SiYuan node-ID format (YYYYMMDDhhmmss-abcdefg style accepted by ast.IsNodeIDPattern)
Sanitize the caller's session ID to conform to the node-ID pattern before calling the API
If the session came from a prior API response, pass that ID through unchanged instead of reformatting it

Example fix

// before: arbitrary session key
saveAgentTodos(conv.ID, todos); // e.g. "org/conv/123"
// after: use a valid node ID
const sessionId = new Date().toISOString().replace(/[-:TZ.]/g, "") + "-" + random7Chars();
saveAgentTodos(sessionId, todos);

Defensive patterns

Strategy: validation

Validate before calling

const NODE_ID_RE = /^\d{14}-[0-9a-z]{7}$/;
if (!NODE_ID_RE.test(sessionId)) {
  throw new Error('session ID must be a SiYuan node ID');
}
await fetchPost('/api/ai/agent/todo/write', {sessionID: sessionId, todos});

Type guard

const isValidSessionId = (id) =>
  typeof id === 'string' && /^\d{14}-[0-9a-z]{7}$/.test(id);

Try / catch

try {
  await saveAgentTodos(sessionId, todos);
} catch (e) {
  if (String(e.message).includes('invalid Agent session ID')) {
    sessionId = newNodeId(); // regenerate in valid format and retry
    await saveAgentTodos(sessionId, todos);
  } else { throw e; }
}

Prevention

Always derive session IDs from SiYuan node IDs, never client-generated UUIDs
Validate IDs against the node-ID pattern before any kernel call
Never build session paths manually; pass the ID and let the kernel compose the path

When it happens

Trigger: Calling SaveAgentTodos (or the todoWriteHandler HTTP endpoint) with a sessionID that is not a valid node ID (empty string, contains '/' or '..' traversal, arbitrary UUID, or other malformed identifier).

Common situations: Client generates its own session IDs (UUIDs) instead of using SiYuan node IDs; an agent framework passes a conversation key with slashes; sessionID empty because a previous lookup failed and returned ''.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/732f9b40ddc7e777. Report an issue: GitHub.