refactor: extract shared agent resolution + add --since/--until to traces list

Extract duplicate agent resolution logic into a shared resolve-agent utility
(src/cli/operations/resolve-agent.ts) used by both logs and traces commands.
Move time-parser to shared utils (src/lib/utils/time-parser.ts). Add --since
and --until flags to `traces list` for custom time range queries instead of
the hardcoded 12h window.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jesseturner21

src/cli/commands/logs/__tests__/action.test.ts

@@ -1,5 +1,5 @@
 import { detectMode, formatLogLine, resolveAgentContext } from '../action';
-import type { LogsContext } from '../action';
+import type { AgentResolutionContext } from '../action';
 import { describe, expect, it } from 'vitest';
 
 describe('detectMode', () => {
@@ -39,7 +39,7 @@ describe('formatLogLine', () => {
 
 describe('resolveAgentContext', () => {
   // Use 'as any' to avoid branded type issues with FilePath/DirectoryPath
-  const makeContext = (overrides?: Partial<LogsContext>): LogsContext => ({
+  const makeContext = (overrides?: Partial<AgentResolutionContext>): AgentResolutionContext => ({
     project: {
       name: 'TestProject',
       version: 1,

src/cli/commands/logs/__tests__/time-parser.test.ts

@@ -1,4 +1,4 @@
-import { parseTimeString } from '../time-parser';
+import { parseTimeString } from '../../../../lib/utils/time-parser';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 describe('parseTimeString', () => {

src/cli/commands/logs/action.ts

@@ -1,15 +1,11 @@
-import { ConfigIO } from '../../../lib';
-import type { AgentCoreProjectSpec, AwsDeploymentTargets, DeployedState } from '../../../schema';
+import { parseTimeString } from '../../../lib/utils';
 import { searchLogs, streamLogs } from '../../aws/cloudwatch';
+import type { AgentResolutionContext } from '../../operations/resolve-agent';
+import { loadAgentResolutionContext, resolveAgent } from '../../operations/resolve-agent';
 import { VALID_LEVELS, buildFilterPattern } from './filter-pattern';
-import { parseTimeString } from './time-parser';
 import type { LogsOptions } from './types';
 
-export interface LogsContext {
-  project: AgentCoreProjectSpec;
-  deployedState: DeployedState;
-  awsTargets: AwsDeploymentTargets;
-}
+export type { AgentResolutionContext };
 
 export interface AgentContext {
   agentId: string;
@@ -25,17 +21,6 @@ export interface LogsResult {
   error?: string;
 }
 
-/**
- * Loads configuration required for logs
- */
-export async function loadLogsConfig(configIO: ConfigIO = new ConfigIO()): Promise<LogsContext> {
-  return {
-    project: await configIO.readProjectSpec(),
-    deployedState: await configIO.readDeployedState(),
-    awsTargets: await configIO.readAWSDeploymentTargets(),
-  };
-}
-
 /**
  * Detect whether to stream or search based on options
  */
@@ -61,73 +46,23 @@ export function formatLogLine(event: { timestamp: number; message: string }, jso
  * Resolve agent context from config + options
  */
 export function resolveAgentContext(
-  context: LogsContext,
+  context: AgentResolutionContext,
   options: LogsOptions
 ): { success: true; agentContext: AgentContext } | { success: false; error: string } {
-  const { project, deployedState, awsTargets } = context;
-
-  if (project.agents.length === 0) {
-    return { success: false, error: 'No agents defined in agentcore.json' };
-  }
-
-  // Resolve agent
-  const agentNames = project.agents.map(a => a.name);
-
-  if (!options.agent && project.agents.length > 1) {
-    return {
-      success: false,
-      error: `Multiple agents found. Use --agent to specify one: ${agentNames.join(', ')}`,
-    };
+  const result = resolveAgent(context, options);
+  if (!result.success) {
+    return { success: false, error: result.error };
   }
-
-  const agentSpec = options.agent ? project.agents.find(a => a.name === options.agent) : project.agents[0];
-
-  if (options.agent && !agentSpec) {
-    return {
-      success: false,
-      error: `Agent '${options.agent}' not found. Available: ${agentNames.join(', ')}`,
-    };
-  }
-
-  if (!agentSpec) {
-    return { success: false, error: 'No agents defined in agentcore.json' };
-  }
-
-  // Resolve target
-  const targetNames = Object.keys(deployedState.targets);
-  if (targetNames.length === 0) {
-    return { success: false, error: 'No deployed targets found. Run `agentcore deploy` first.' };
-  }
-  const selectedTargetName = targetNames[0]!;
-
-  const targetState = deployedState.targets[selectedTargetName];
-  const targetConfig = awsTargets.find(t => t.name === selectedTargetName);
-
-  if (!targetConfig) {
-    return { success: false, error: `Target config '${selectedTargetName}' not found in aws-targets` };
-  }
-
-  // Get the deployed state for this specific agent
-  const agentState = targetState?.resources?.agents?.[agentSpec.name];
-
-  if (!agentState) {
-    return {
-      success: false,
-      error: `Agent '${agentSpec.name}' is not deployed to target '${selectedTargetName}'. Run 'agentcore deploy' first.`,
-    };
-  }
-
-  const agentId = agentState.runtimeId;
+  const { agent } = result;
   const endpointName = 'DEFAULT';
-  const logGroupName = `/aws/bedrock-agentcore/runtimes/${agentId}-${endpointName}`;
-
+  const logGroupName = `/aws/bedrock-agentcore/runtimes/${agent.runtimeId}-${endpointName}`;
   return {
     success: true,
     agentContext: {
-      agentId,
-      agentName: agentSpec.name,
-      accountId: targetConfig.account,
-      region: targetConfig.region,
+      agentId: agent.runtimeId,
+      agentName: agent.agentName,
+      accountId: agent.accountId,
+      region: agent.region,
       endpointName,
       logGroupName,
     },
@@ -146,7 +81,7 @@ export async function handleLogs(options: LogsOptions): Promise<LogsResult> {
     };
   }
 
-  const context = await loadLogsConfig();
+  const context = await loadAgentResolutionContext();
   const resolution = resolveAgentContext(context, options);
 
   if (!resolution.success) {

src/cli/commands/traces/action.ts

@@ -1,81 +1,9 @@
-import { ConfigIO } from '../../../lib';
-import type { AgentCoreProjectSpec, AwsDeploymentTargets, DeployedState } from '../../../schema';
-import { buildTraceConsoleUrl, getTrace, listTraces, parseRuntimeArn } from '../../operations/traces';
+import { parseTimeString } from '../../../lib/utils';
+import type { AgentResolutionContext } from '../../operations/resolve-agent';
+import { resolveAgent } from '../../operations/resolve-agent';
+import { buildTraceConsoleUrl, getTrace, listTraces } from '../../operations/traces';
 import type { TracesGetOptions, TracesListOptions } from './types';
 
-export interface TracesContext {
-  project: AgentCoreProjectSpec;
-  deployedState: DeployedState;
-  awsTargets: AwsDeploymentTargets;
-}
-
-export async function loadTracesConfig(configIO: ConfigIO = new ConfigIO()): Promise<TracesContext> {
-  return {
-    project: await configIO.readProjectSpec(),
-    deployedState: await configIO.readDeployedState(),
-    awsTargets: await configIO.readAWSDeploymentTargets(),
-  };
-}
-
-interface ResolvedAgent {
-  agentName: string;
-  region: string;
-  accountId: string;
-  runtimeId: string;
-  targetName: string;
-}
-
-function resolveAgent(context: TracesContext, options: { agent?: string }): ResolvedAgent | { error: string } {
-  const { project, deployedState, awsTargets } = context;
-
-  const targetNames = Object.keys(deployedState.targets);
-  if (targetNames.length === 0) {
-    return { error: 'No deployed targets found. Run `agentcore deploy` first.' };
-  }
-
-  const selectedTargetName = targetNames[0]!;
-  const targetState = deployedState.targets[selectedTargetName];
-  const targetConfig = awsTargets.find(t => t.name === selectedTargetName);
-  if (!targetConfig) {
-    return { error: `Target config '${selectedTargetName}' not found in aws-targets` };
-  }
-
-  if (project.agents.length === 0) {
-    return { error: 'No agents defined in configuration' };
-  }
-
-  const agentNames = project.agents.map(a => a.name);
-  if (!options.agent && project.agents.length > 1) {
-    return { error: `Multiple agents found. Use --agent to specify one: ${agentNames.join(', ')}` };
-  }
-
-  const agentSpec = options.agent ? project.agents.find(a => a.name === options.agent) : project.agents[0];
-  if (options.agent && !agentSpec) {
-    return { error: `Agent '${options.agent}' not found. Available: ${agentNames.join(', ')}` };
-  }
-  if (!agentSpec) {
-    return { error: 'No agents defined in configuration' };
-  }
-
-  const agentState = targetState?.resources?.agents?.[agentSpec.name];
-  if (!agentState) {
-    return { error: `Agent '${agentSpec.name}' is not deployed to target '${selectedTargetName}'` };
-  }
-
-  const parsed = parseRuntimeArn(agentState.runtimeArn);
-  if (!parsed) {
-    return { error: `Could not parse runtime ARN: ${agentState.runtimeArn}` };
-  }
-
-  return {
-    agentName: agentSpec.name,
-    region: targetConfig.region,
-    accountId: parsed.accountId,
-    runtimeId: parsed.runtimeId,
-    targetName: selectedTargetName,
-  };
-}
-
 export interface TracesListResult {
   success: boolean;
   agentName?: string;
@@ -85,25 +13,43 @@ export interface TracesListResult {
   error?: string;
 }
 
-export async function handleTracesList(context: TracesContext, options: TracesListOptions): Promise<TracesListResult> {
+export async function handleTracesList(
+  context: AgentResolutionContext,
+  options: TracesListOptions
+): Promise<TracesListResult> {
   const resolved = resolveAgent(context, options);
-  if ('error' in resolved) {
+  if (!resolved.success) {
     return { success: false, error: resolved.error };
   }
 
+  const { agent } = resolved;
+
   const consoleUrl = buildTraceConsoleUrl({
-    region: resolved.region,
-    accountId: resolved.accountId,
-    runtimeId: resolved.runtimeId,
-    agentName: resolved.agentName,
+    region: agent.region,
+    accountId: agent.accountId,
+    runtimeId: agent.runtimeId,
+    agentName: agent.agentName,
   });
 
   const limit = options.limit ? parseInt(options.limit, 10) : 20;
+
+  // Parse time options
+  let startTime: number | undefined;
+  let endTime: number | undefined;
+  if (options.since) {
+    startTime = parseTimeString(options.since);
+  }
+  if (options.until) {
+    endTime = parseTimeString(options.until);
+  }
+
   const result = await listTraces({
-    region: resolved.region,
-    runtimeId: resolved.runtimeId,
-    agentName: resolved.agentName,
+    region: agent.region,
+    runtimeId: agent.runtimeId,
+    agentName: agent.agentName,
     limit,
+    startTime,
+    endTime,
   });
 
   if (!result.success) {
@@ -112,8 +58,8 @@ export async function handleTracesList(context: TracesContext, options: TracesLi
 
   return {
     success: true,
-    agentName: resolved.agentName,
-    targetName: resolved.targetName,
+    agentName: agent.agentName,
+    targetName: agent.targetName,
     consoleUrl,
     traces: result.traces,
   };
@@ -129,26 +75,28 @@ export interface TracesGetResult {
 }
 
 export async function handleTracesGet(
-  context: TracesContext,
+  context: AgentResolutionContext,
   traceId: string,
   options: TracesGetOptions
 ): Promise<TracesGetResult> {
   const resolved = resolveAgent(context, options);
-  if ('error' in resolved) {
+  if (!resolved.success) {
     return { success: false, error: resolved.error };
   }
 
+  const { agent } = resolved;
+
   const consoleUrl = buildTraceConsoleUrl({
-    region: resolved.region,
-    accountId: resolved.accountId,
-    runtimeId: resolved.runtimeId,
-    agentName: resolved.agentName,
+    region: agent.region,
+    accountId: agent.accountId,
+    runtimeId: agent.runtimeId,
+    agentName: agent.agentName,
   });
 
   const result = await getTrace({
-    region: resolved.region,
-    runtimeId: resolved.runtimeId,
-    agentName: resolved.agentName,
+    region: agent.region,
+    runtimeId: agent.runtimeId,
+    agentName: agent.agentName,
     traceId,
     outputPath: options.output,
   });
@@ -159,8 +107,8 @@ export async function handleTracesGet(
 
   return {
     success: true,
-    agentName: resolved.agentName,
-    targetName: resolved.targetName,
+    agentName: agent.agentName,
+    targetName: agent.targetName,
     consoleUrl,
     filePath: result.filePath,
   };

src/cli/commands/traces/command.tsx

@@ -1,7 +1,8 @@
 import { getErrorMessage } from '../../errors';
+import { loadAgentResolutionContext } from '../../operations/resolve-agent';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { requireProject } from '../../tui/guards';
-import { handleTracesGet, handleTracesList, loadTracesConfig } from './action';
+import { handleTracesGet, handleTracesList } from './action';
 import type { TracesGetOptions, TracesListOptions } from './types';
 import type { Command } from '@commander-js/extra-typings';
 import { Box, Text, render } from 'ink';
@@ -24,11 +25,13 @@ export const registerTraces = (program: Command) => {
     .description('List recent traces for a deployed agent')
     .option('--agent <name>', 'Select specific agent')
     .option('--limit <n>', 'Maximum number of traces to display', '20')
+    .option('--since <time>', 'Start time (e.g. 5m, 1h, 2d, ISO 8601, epoch ms)')
+    .option('--until <time>', 'End time (e.g. now, 1h, ISO 8601, epoch ms)')
     .action(async (cliOptions: TracesListOptions) => {
       requireProject();
 
       try {
-        const context = await loadTracesConfig();
+        const context = await loadAgentResolutionContext();
         const result = await handleTracesList(context, cliOptions);
 
         if (!result.success) {
@@ -76,7 +79,7 @@ export const registerTraces = (program: Command) => {
                 ))}
               </>
             ) : (
-              <Text color="yellow">No traces found in the last 12 hours.</Text>
+              <Text color="yellow">No traces found in the specified time range.</Text>
             )}
             <Text> </Text>
             {result.consoleUrl && <Text color="gray">Console: {result.consoleUrl}</Text>}
@@ -97,7 +100,7 @@ export const registerTraces = (program: Command) => {
       requireProject();
 
       try {
-        const context = await loadTracesConfig();
+        const context = await loadAgentResolutionContext();
         const result = await handleTracesGet(context, traceId, cliOptions);
 
         if (!result.success) {

src/cli/commands/traces/index.ts

@@ -1,2 +1,2 @@
 export { registerTraces } from './command';
-export { handleTracesList, handleTracesGet, loadTracesConfig, type TracesContext } from './action';
+export { handleTracesList, handleTracesGet } from './action';