/**
 * Builds the tool ctx object from environment variables.
 * Used by companion-stdio.js when a tool call arrives, so each call reads
 * fresh env values (useful if the process restarts or env is injected at launch).
 *
 * Environment variables:
 *   VOID_AGENT_JSON  – JSON-serialised agent actor object (required for most tools)
 *   VOID_SPACE_ID    – UUID of the active space
 *   VOID_VIEW_JSON   – JSON-serialised view object (optional)
 */
export function buildCtxFromEnv(env = process.env) {
  return {
    agent: env.VOID_AGENT_JSON ? JSON.parse(env.VOID_AGENT_JSON) : null,
    space_id: env.VOID_SPACE_ID || null,
    view: env.VOID_VIEW_JSON ? JSON.parse(env.VOID_VIEW_JSON) : null,
    actor: { kind: 'user', id: null }
  };
}

/**
 * Builds the tool ctx for an authenticated EXTERNAL agent. The Space is taken
 * from the agent's own scope (never client-supplied) and `spaceScoped` is set
 * so read() denies entities it can't prove are in-Space.
 * @param {{id:string, capabilities?:object, scopes?:object}} agent
 */
export function buildCtxFromAgent(agent) {
  const actor = {
    kind: 'agent',
    id: agent.id,
    capabilities: agent.capabilities || {},
    scopes: agent.scopes || {}
  };
  return {
    agent: actor,
    space_id: (agent.scopes && agent.scopes.space_id) || null,
    view: null,
    spaceScoped: true,
    actor
  };
}