feat: Introduce core harness interfaces (Handler, Harness, Execution) (#16)

* feat: Introduce core harness interfaces (Handler, Harness, Execution)

Add the core interfaces for the new execution harness package.
This includes:
- Handler: interface with OnMessage and OnComplete callbacks for streaming turn execution outputs.
- Harness: interface to start interactive execution sessions.
- Execution: interface for managing conversational turns, message queue, IDs, and cleanup.

TAG=agy
CONV=c1af32c9-35e7-4583-bbd2-3be946e45699

* refactor: Make Queue parameter variadic for multi-message support

Update the Queue method signature on the Execution interface to accept
a variadic parameter of messages. This allows callers to queue a single
message or multiple messages in one go.

TAG=agy
CONV=c1af32c9-35e7-4583-bbd2-3be946e45699

Author: anj-s

internal/harness/harness.go

@@ -0,0 +1,54 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package harness defines a common execution boundary and lifecycle hooks
+// for interacting with agents, planners, or external gRPC services.
+package harness
+
+import (
+	"context"
+
+	"github.com/google/ax/proto"
+)
+
+// Handler defines the streaming event hook callbacks for an execution turn.
+type Handler interface {
+	// OnMessage is invoked when the agent generates output content during its turn.
+	OnMessage(ctx context.Context, execID string, msg *proto.Message) error
+
+	// OnComplete is invoked when the agent finishes its current execution turn.
+	OnComplete(ctx context.Context, execID string) error
+}
+
+// Harness represents a service capable of starting execution sessions.
+type Harness interface {
+	// Start initializes a new Execution session for a conversation.
+	Start(ctx context.Context, conversationID string) (Execution, error)
+}
+
+// Execution represents an active interactive session with an agent or planner.
+type Execution interface {
+	// Run executes the session and streams events to the provided Handler.
+	// It blocks until the current turn completes or fails.
+	Run(ctx context.Context, handler Handler) error
+
+	// Queue enqueues new input messages to be processed in the next turn.
+	Queue(ctx context.Context, msg ...*proto.Message) error
+
+	// ID returns the unique execution session ID.
+	ID() string
+
+	// Close cleanly releases all resources associated with the execution session.
+	Close(ctx context.Context) error
+}