feat(project): add project-aware invoke

README.md

@@ -31,6 +31,7 @@ Identity, and Gateway branches and leaves open their interactive flows.
 
 ```
 agentcore                          # interactive TUI
+├── invoke                         # project-aware invoke shorthand (requires a project)
 ├── harness                        # manage agentcore harnesses
 │   ├── create                     # create a harness (auto-provisions a role if none given)
 │   ├── get                        # fetch a harness by id
@@ -104,6 +105,15 @@ agentcore                          # interactive TUI
 │       ├── get                    # get an evaluator by id (type-agnostic)
 │       ├── list                   # list evaluators (server-side paginated)
 │       └── delete                 # delete an evaluator by id
+├── project                        # manage an AgentCore project
+│   ├── create                     # create a project
+│   ├── add                        # add project resources
+│   ├── remove                     # remove project resources
+│   ├── dev                        # run the project locally
+│   ├── deploy                     # deploy the project
+│   ├── invoke                     # invoke a project Runtime or Harness
+│   ├── status                     # inspect deployed project resources
+│   └── build                      # synthesize deployable artifacts
 └── config                         # read/write global config values
 ```
 
@@ -116,6 +126,42 @@ Global flags (declared at the root, available on every command):
 | `--debug`        | Debug logging.                                                       |
 | `--endpoint-url` | Override the service endpoint URL (e.g. for testing against a stub). |
 
+### Invoke a project resource
+
+From anywhere inside an AgentCore project, invoke a deployed Runtime or Harness
+by its logical project name:
+
+```bash
+# A project with exactly one Runtime or Harness needs no selector.
+agentcore project invoke "Summarize this repository."
+
+# Select explicitly when the project has multiple invokable resources.
+agentcore project invoke --runtime checkout "Check order 123."
+agentcore project invoke --harness support "Help with my account."
+
+# Select another deployment target.
+agentcore project invoke --target staging --runtime checkout "Run a smoke test."
+
+# Preserve the Runtime wire response in a JSON envelope.
+agentcore project invoke --runtime checkout "Check order 123." --json
+
+# Omit content to open the selected resource's interactive console.
+agentcore project invoke --runtime checkout
+
+# Omit content and selectors to choose from the project's Runtimes and Harnesses.
+agentcore project invoke
+
+# The project-aware shorthand has the same behavior inside a project.
+agentcore invoke
+```
+
+Project Runtime content is sent as `{"prompt": content}` with
+`application/json`. `--target` defaults to `default` and supplies the AWS
+account and region used for resource lookup and invocation. Default output
+streams assistant text from supported Strands SSE responses and passes
+unsupported SSE responses through unchanged. `--json` preserves the exact wire
+response instead.
+
 ### Examples
 
 ```bash

src/assets/templates/hello-world-python-container/README.md

@@ -25,3 +25,9 @@ Environment variables for local development go in `agentcore/.env.local`
 ```bash
 agentcore project deploy
 ```
+
+Invoke the deployed Runtime:
+
+```bash
+agentcore project invoke "Hello!"
+```

src/assets/templates/hello-world-python/README.md

@@ -27,9 +27,6 @@ curl -X POST http://localhost:8080/invocations \
   -d '{"prompt": "Hello!"}'
 ```
 
-<!-- TODO: replace the uv run + curl instructions with `agentcore dev` and
-     `agentcore invoke` once those commands are available. -->
-
 ## Build your agent
 
 Start in `main.py`:
@@ -58,3 +55,8 @@ for multi-agent patterns, MCP tools, and model configuration.
 
 Deploy from the project root with the AgentCore CLI; the CDK app under
 `agentcore/cdk` provisions the Runtime that hosts this agent.
+
+```bash
+agentcore project deploy
+agentcore project invoke "Hello!"
+```

src/assets/templates/strands-http-python/README.md

@@ -38,3 +38,12 @@ Command Prompt, or `.\.venv\Scripts\activate.ps1` in Windows PowerShell.
 # Deployment
 
 After providing credentials, `agentcore project deploy` will deploy your project into Amazon Bedrock AgentCore.
+
+Invoke the deployed Runtime from the project root:
+
+```bash
+agentcore project invoke "Hello!"
+```
+
+The CLI sends `{"prompt": content}` and streams assistant text from the Strands response. Use `--json` to preserve
+the exact wire response.

src/components/PaginatedTablePicker.tsx

@@ -1,5 +1,6 @@
 import { keepPreviousData, useQuery } from "@tanstack/react-query";
 import { Text, useInput } from "ink";
+import { useEffect, useRef } from "react";
 import { Layout } from "./Layout";
 import { usePagedList } from "./usePagedList";
 import { darkTheme } from "./ui/_core.js";
@@ -27,6 +28,7 @@ export interface PaginatedTablePickerProps<TItem, TRow extends Record<string, un
   emptyMessage: string;
   emptyPageMessage: string;
   maxPageSize?: number;
+  autoSelectSingle?: boolean;
 }
 
 export function PaginatedTablePicker<TItem, TRow extends Record<string, unknown>>({
@@ -45,6 +47,7 @@ export function PaginatedTablePicker<TItem, TRow extends Record<string, unknown>
   emptyMessage,
   emptyPageMessage,
   maxPageSize,
+  autoSelectSingle = false,
 }: PaginatedTablePickerProps<TItem, TRow>) {
   const paging = usePagedList(maxPageSize);
   const list = useQuery({
@@ -57,6 +60,27 @@ export function PaginatedTablePicker<TItem, TRow extends Record<string, unknown>
   const pageTransition = list.isFetching && !list.isPending;
   const mappedRows = (list.data?.items ?? []).map(toRow);
   const rows = sortRows ? sortRows(mappedRows) : mappedRows;
+  const autoSelectIdentity = JSON.stringify(queryKey);
+  const lastAutoSelection = useRef<string | undefined>(undefined);
+  const autoSelectValue =
+    autoSelectSingle &&
+    !list.isPending &&
+    !list.isError &&
+    !list.isFetching &&
+    paging.pageIndex === 0 &&
+    nextToken === undefined &&
+    rows.length === 1
+      ? getValue(rows[0]!)
+      : undefined;
+  const autoSelecting =
+    autoSelectValue !== undefined &&
+    lastAutoSelection.current !== `${autoSelectIdentity}:${autoSelectValue}`;
+
+  useEffect(() => {
+    if (!autoSelecting || autoSelectValue === undefined) return;
+    lastAutoSelection.current = `${autoSelectIdentity}:${autoSelectValue}`;
+    onSelect(autoSelectValue);
+  }, [autoSelectIdentity, autoSelectValue, autoSelecting, onSelect]);
 
   useInput(
     (input, key) => {
@@ -70,15 +94,15 @@ export function PaginatedTablePicker<TItem, TRow extends Record<string, unknown>
       }
       if (input === "r" && list.isError) void list.refetch();
     },
-    { isActive: list.isPending || list.isError || pageTransition },
+    { isActive: list.isPending || list.isError || pageTransition || autoSelecting },
   );
 
   return (
     <Layout
       breadcrumb={breadcrumb}
       description={description}
       keyHints={[
-        ...(!list.isPending && !list.isError && !pageTransition
+        ...(!list.isPending && !list.isError && !pageTransition && !autoSelecting
           ? [
               { key: "↑↓/jk", label: "navigate" },
               ...(paginated ? [{ key: "←→/hl", label: "page" }] : []),
@@ -92,8 +116,8 @@ export function PaginatedTablePicker<TItem, TRow extends Record<string, unknown>
         { key: "ctl+c", label: "quit" },
       ]}
     >
-      {list.isPending ? (
-        <Spinner label={loadingMessage} />
+      {list.isPending || autoSelecting ? (
+        <Spinner label={list.isPending ? loadingMessage : "Opening…"} />
       ) : list.isError ? (
         <Text color="red">{errorMessage(list.error as Error)}</Text>
       ) : (

src/components/Root.tsx

@@ -107,6 +107,7 @@ import { GatewayRuleScreen } from "../handlers/gateway/rule/screen.tsx";
 import { GatewayRuleListScreen } from "../handlers/gateway/rule/list/screen.tsx";
 import { GatewayRuleGetScreen } from "../handlers/gateway/rule/get/screen.tsx";
 import { GatewayInvokeScreen } from "../handlers/gateway/invoke/screen.tsx";
+import { ProjectInvokePickerScreen } from "../handlers/project/invoke/screen.tsx";
 import { RootScreen, HelpScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
 
@@ -140,6 +141,10 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
       <MemoryRouter initialEntries={[path]}>
         <Routes>
           <Route path="agentcore" element={<RootScreen ctx={ctx} core={core} />} />
+          <Route
+            path="agentcore/project/invoke"
+            element={<ProjectInvokePickerScreen ctx={ctx} core={core} />}
+          />
           <Route path="agentcore/harness" element={<HarnessScreen ctx={ctx} core={core} />} />
           {/* Bare `get` (no id) has nothing to show — send the user to the list. */}
           <Route

src/components/RouterScreen.test.tsx

@@ -32,6 +32,13 @@ describe("menu rendering", () => {
     r.unmount();
   });
 
+  test("does not offer the project-only invoke alias in the root menu", async () => {
+    const r = renderScreen("/agentcore");
+    await waitForText(r.lastFrame, "harness");
+    expect(r.lastFrame()).not.toMatch(/^[❯ ]*invoke\s/m);
+    r.unmount();
+  });
+
   test("renders the harness subcommands when mounted at the harness path", async () => {
     const r = renderScreen("/agentcore/harness");
     await waitForText(r.lastFrame, "list");

src/components/RuntimeEndpointPicker.tsx

@@ -43,6 +43,7 @@ export interface RuntimeEndpointPickerProps extends ScreenProps {
   description?: string;
   onSelect: (qualifier: string) => void;
   onEscape?: () => void;
+  autoSelectSingle?: boolean;
 }
 
 export function RuntimeEndpointPicker({
@@ -53,6 +54,7 @@ export function RuntimeEndpointPicker({
   description,
   onSelect,
   onEscape,
+  autoSelectSingle,
 }: RuntimeEndpointPickerProps) {
   const opts = coreOptsFromCtx(ctx);
   const navigate = useNavigate();
@@ -79,6 +81,7 @@ export function RuntimeEndpointPicker({
       errorMessage={(error) => `Error loading endpoints for Runtime ${runtimeId}: ${error.message}`}
       emptyMessage="This Runtime has no endpoints."
       emptyPageMessage={`No endpoints on this page for Runtime ${runtimeId}.`}
+      autoSelectSingle={autoSelectSingle}
     />
   );
 }

src/core/project/agentEventParser.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test";
+import { parseAgentEvent, type AgentEvent } from "./agentEventParser";
+
+describe("parseAgentEvent", () => {
+  test.each([
+    {
+      name: "JSON string",
+      data: JSON.stringify("string token"),
+      expected: { kind: "text", text: "string token" },
+    },
+    {
+      name: "text object",
+      data: JSON.stringify({ text: "text token" }),
+      expected: { kind: "text", text: "text token" },
+    },
+    {
+      name: "Converse text delta",
+      data: JSON.stringify({
+        event: { contentBlockDelta: { delta: { text: "delta token" } } },
+      }),
+      expected: { kind: "text", text: "delta token" },
+    },
+    {
+      name: "non-JSON token",
+      data: "raw token",
+      expected: { kind: "text", text: "raw token" },
+    },
+  ] satisfies { name: string; data: string; expected: AgentEvent }[])(
+    "extracts a $name",
+    ({ data, expected }) => {
+      expect(parseAgentEvent(data)).toEqual(expected);
+    },
+  );
+
+  test("extracts an error object", () => {
+    expect(parseAgentEvent(JSON.stringify({ error: "model denied" }))).toEqual({
+      kind: "error",
+      message: "model denied",
+    });
+  });
+
+  test.each([
+    {
+      name: "message start",
+      data: JSON.stringify({ event: { messageStart: { role: "assistant" } } }),
+    },
+    {
+      name: "message stop",
+      data: JSON.stringify({ event: { messageStop: { stopReason: "end_turn" } } }),
+    },
+    {
+      name: "content block start",
+      data: JSON.stringify({
+        event: { contentBlockStart: { start: { toolUse: { name: "weather" } } } },
+      }),
+    },
+    {
+      name: "non-text content block delta",
+      data: JSON.stringify({
+        event: { contentBlockDelta: { delta: { toolUse: { input: "{}" } } } },
+      }),
+    },
+    {
+      name: "content block stop",
+      data: JSON.stringify({ event: { contentBlockStop: { contentBlockIndex: 0 } } }),
+    },
+    {
+      name: "metadata",
+      data: JSON.stringify({ event: { metadata: { usage: { totalTokens: 1 } } } }),
+    },
+    { name: "empty JSON string", data: JSON.stringify("") },
+    { name: "blank text", data: JSON.stringify({ text: "" }) },
+    { name: "blank error", data: JSON.stringify({ error: "" }) },
+    { name: "empty non-JSON token", data: "" },
+  ])("identifies $name as control", ({ data }) => {
+    expect(parseAgentEvent(data)).toEqual({ kind: "control" });
+  });
+
+  test.each([
+    { name: "unknown object", data: JSON.stringify({ progress: 1 }) },
+    { name: "JSON number", data: JSON.stringify(42) },
+    { name: "JSON boolean", data: JSON.stringify(true) },
+    { name: "JSON null", data: JSON.stringify(null) },
+    { name: "JSON array", data: JSON.stringify(["token"]) },
+    { name: "malformed event", data: JSON.stringify({ event: "not-an-object" }) },
+    {
+      name: "unknown event envelope",
+      data: JSON.stringify({ event: { customDelta: { text: "must survive" } } }),
+    },
+  ])("identifies an unsupported $name", ({ data }) => {
+    expect(parseAgentEvent(data)).toEqual({ kind: "unsupported" });
+  });
+});